We are slowly moving towards better-standardized commenting in a large C++ project, introducing Doxygen. I personally find it a pain typing in comments, especially since Java IDEs are so good at automating this.
So I wondered what tools there might be? A search turned up DoxyComment which looks quite nice, is this the best/standard tool or are there others worth a look too?
Atomineer is a tool that I and a few others have been using for documenting unmanaged C++ code with Doxygen markup. It's not free, but it is cheap, and may be worth a try:
http://www.atomineerutils.com/products.php
If typing the meta-comments which are instructions to doxygen is a significant part of your comment-writing effort, you're doing it wrong.
Comment should not include things which can be automatically determined by a tool, any programmer will determine just as much (or more) information from e.g. parameter names than any tool.
Another way to look at this is that doxygen already does an excellent job of presenting what can be automatically determined. You don't need to write: "B::B constructs a B object", since doxygen is going to sort it into the constructors section of the documentation automatically.
Focus on what's non-obvious, and take time to think about what you're writing.
Normally many functions and variables will have no need for an individual comment, since either the name is descriptive enough, or they are better explained in a class-level comment describing how multiple members interact.
Related
I am looking for a good tool that can automatically convert c++ naming styles, such as change method name from "SetPosition()" to "setPosition()", and class name "CPoint" to "Point". Seems most of formatters have no such feature. Thanks.
You can manipulate C++ source using Clang, although you might have to write a bit of code to do the conversion that you have in mind.
For example, the Clang infrastructure would allow you to write a program that iterates over all class method names in a given source file. You could then programatically convert any pascal-case method names that you encounter into camel-case names.
Code formatters don't do renaming of functions. What you need is a refactoring tool that can perform rename. If your project isn't very big then Devexpress Refactor! for C++ (free) might be of help. It will involve some manual work, but it'll be safer than search and replace. Qt Creator has a rename reporting built in an I have found it to be quite reliable (hasn't messed up so far unlike some dedicated refactoring tools).
If manual work using refactoring tools is too much then you can use clangs pieces to build a tool that performs the refactorings automatically, but this is probably more work than the semi-manual process with refactoring tools.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
A free tool to check C/C++ source code against a set of coding standards?
I am starting a c++ project involving several people I have no direct access to. We agreed on a coding style guide, which e.g. defines the casing for class members depending on the accessibility (i.e. privates in pascal case, publics and protecteds in camel case. Please, don't start discussions about the style guide. I had enough. Thank you.).
What I want to do now is to generate some reporting of style guide violations. I don't want to enforce the style guide, e.g. at commit, but I want to provide a tool which each developer can use to see where his/her code violates the style guide (if he/she wants to check it).
Do you know a tool which can do the Job?
(It needs to be able to understand some C++, e.g. to detect the accessibility of class members.)
well, you could run your code through AStyle or Uncrustify on commit, which would at least re-format bad code to some standard. I find that's the majority problem with code commits and standards - if you reformat after commmit, it shows up as a lot of delta changes that are entirely trivial.
Otherwise, check the other SO answer.
Style guides tends to be company-specific, and one has to write company-specific checks to achieve them.
My company offers customizable C++ style checkers, in which one can check for deprecated idioms by syntax, check that variables and types have certain properties, or verify that certain commands occur in certain orders locally. These checkers use C++ dialect precise parsers on the source code. The customization isn't easy; you need the underlying engine and some knowledge of parsing C++ programs.
It is possible to write rules that check for layout, but it is a lot of unrewarding work, and resolving such complaints isn't a productive use of programmer resource IMHO. And if you aren't going to enforce your style, why are you annoying the programmer with complaints at all? IT seems easier (as another poster noted) to simply run a layout-formatter that produces the right result at no cost to the programmer.
One of the issues with generic formatters is that being language-imprecise, they may misinterpret the source code and sometimes break it as they format, leading to compilation errors, debugging and wasted time. We also offer C++ Formatters to accomplish the formatting using the same language precise parsers as the style checker; they can't break your code during reformatting.
I've been successfully using the vera++ tool to do this for our projects. I've wrote a number of rules (in TCL) to adopt our company style guidelines. It was a bit painful, until I came around all the false positives reported from my checks. At least it's working well now and I have integrated the reports to the Jenkins build analysis.
The reports can also be easily adopted to a custom error analysis in the Eclipse IDE.
I am trying to understand a C++ codebase. I have used some free tools that will scan the code and produce diagrams, but they are not so easy to understand.
What I think would be useful is to manually construct something assisted by the UML tool.
What i need is to create something that looks like the data structure at run-time. Ideally by pulling objects from the UML and arranging them. Also I would like to organise the classes in sub-packages - like those close to the DB, or towards the branches of the datastructures.
(I am partly doing this now with Folders in the Visual Studio Solution explorer)
This is a LINUX project with many Makesfiles, but many tools like Visual Studio, "understands" the code when I just create projects with the files in the main directory of the exe I am working on
Most tools will only give you a structural view (classes and packages), which honestly doesn't tell you that much of what goes on in runtime.
Enterprise Architect from Sparx Systems incorporates a Visual Execution Analyzer, which can generate sequence diagrams from a debug session. It supports C++ but only on Windows so you'd have to rebuild, but if I understand you correctly you've already got your code running in Visual Studio.
Here's a brief demo (in this case the code is in C#, but they do claim to support C++ as well). This isn't a full-roundtrip, write-the-code-in-UML kind of thing, but personally I think that's a pipe dream anyway. Use UML to document, use a programming language to code.
Honestly, you might have substantial problems getting anything useful out of a UML tool with regard to reverse generating code.
If the code is unusually clean and had a decent OO design, good containment, inheritance, and few associations theres a chance that it might look alright... but with most real projects, when you reverse generate into UML, the resulting diagrams are a spidery mess that will probably do more harm than good.
If you are going to stick with the reverse-model genreation though, try and configure the UML utility to show less items - keep it to the key relationships like aggregation and inheritance. When you start showing uses relationships rather than contains/aggregation relationships then everything tends to connect to everything unless the project was very well written, and that will just lead to more confusion and micsonceptions.
My best recommendation would be - if the tool makes it look incomprehensible, save yourself some time and do it yourself.
UML and C++ code that wasn't generated from UML don't play together that nicely. Especially as soon as templates are involved you might get into more trouble then you would actually like and you need to ask yourself if the time spent into getting those models isn't actually better invested in good old-fashioned source code reading. You will have to read the code eventually to understand what it does so just get started now.
Didn't understand if it's linux or windows (you say linux, but then say you're using visual studio).
If you want to understand the code, Source Insight is a good tool for that. Not necessarily UMLs, but produces nice graphs in real time.
We are going to start a new project in our team which consists of less than 10 developers.
We have access to modern IDEs such as VS2010.
The project is extremely dynamic (users' needs change very quick) and cross platform. Therefore, I need a highly readable and very detailed C++ coding standard so new developers can easily change the old codes in future. I also need a not to write list so the code will compile on different OSes (at least windows and linux).
Is there such a standard?
Are coding standards expired already?
Coding standards remain an issue because everyone secretly thinks they can solve all the world's programming problems with a very clever coding standard. And then forcing programmers to follow them. (Pretty much like programming programmers.)
Unfortunately, few coding standards address the issues that matter in a complex project like:
how to cleanly and effectively partition and model a problem
how program partitions should best interact with others
how an explanation of logic ("comment") should be written to explain the code
Instead, most coding standards address trivia like:
indentation and brace style
whether comments should be present or not
mechanical rules about constructing identifiers
placing arbitrary limits on characters in a line, number of parameters, etc., etc.
As for the primary question, I don't know of any good detailed standards other than design and implement code which other engineers would be proud of.
Read C++ Coding Standards. It is not what most people would call a coding standards document, but you probably want to read it. One of the first guides is do not swell the small stuff (do not put too much emphasis on details: focus on rules that affect the semantic not the syntax, as in prefer RAII over raw pointers instead of add braces everywhere, in it's own line and indenting 3 spaces)
As far as coding standard go, in most cases, it's less important what the specific coding standards are, so long as they're firmly in place. Tabs vs. space? Who cares. Pick one and go with it. Curly braces on the same line as the conditional or the next line? Who cares. Pick one and stay consistent.
I personally like the Linux kernel coding standards.
http://www.kernel.org/doc/Documentation/CodingStyle
It is for C, and not C++, but it may be a good place to start on the standards for your project. Unfortunately, I doubt it offers suggestions on a "do not write" list.
I highly recommend the Google style guide, which I haven't stopped using since interning there two years ago. The link above enumerates the rules in detail, along with each rule's justification in terms of pros and cons.
It is indeed highly readable and very detailed, but the important rules (the ones that come up all the time) are few and easy to remember. They have really streamlined my C++ coding by giving consistency to my naming and function argument-passing conventions.
I know you're using an IDE, but emacs users can use their "google.el" file for automatic formatting. There's also a powerful "cpplint" script that runs through a source file, printing out style violations in the same warning format as used by gcc. This lets you quickly fix style violations before checking in a file. If your IDE can parse gcc warnings and jump from warning to warning in a source file, then fixing such violations becomes a snap. Emacs and Eclipse CDT do this, as do other editors/IDEs.
When programming in C++ in Visual Studio 2008, why is there no functionality like that seen in the refactor menu when using C#?
I use Rename constantly and you really miss it when it's not there. I'm sure you can get plugins that offer this, but why isn't it integrated in to the IDE when using C++? Is this due to some gotcha in the way that C++ must be parsed?
The syntax and semantics of C++ make it incredibly difficult to correctly implement refactoring functionality. It's possible to implement something relatively simple to cover 90% of the cases, but in the remaining 10% of cases that simple solution will horribly break your code by changing things you never wanted to change.
Read http://yosefk.com/c++fqa/defective.html#defect-8 for a brief discussion of the difficulties that any refactoring code in C++ has to deal with.
Microsoft has evidently decided to punt on this particular feature for C++, leaving it up to third-party developers to do what they can.
I'm not sure why it is like this, but third-party tools exist that help. For example, right now I'm evaluating Visual Assist X (by Whole Tomato). We're also using Visual Studio 2005.
devexpress provides Add-in Refactor! for C++ for VS2005 and VS2008.
Don't feel hard-done-by, it isn't available in VB.Net either :)
C++ is a HARD language to parse compared with C# (VB too unless you've "Option Explicit" and "Option Strict" switched on, it's difficult to tell exactly what any line of code is doing out of a MUCH larger context).
At a guess it could have something to do with the "difficulty" of providing it.
P.S. I marked my answer as community wiki because I know it's not providing any useful information.
Eclipse does few c++ refactorings including 'rename'. Check out this question here on StackOverflow.
It is also possible to use Microsoft compiler with Eclipse. Check out here.
Try Eclipse and see if it fits for you.
There is a lot of fud and confusion around this issue. This amazing youtube video should clear up why C++ refactoring is hard: https://www.youtube.com/watch?v=mVbDzTM21BQ
tl;dr Google refactors their entire 100 million line C++ codebase by using a compiler (Clang + LLVM) that allows access to its intermediate format.
Bottom line, third parties are screwed here, there is no realistic way for them to refactor VS C++ unless MS outputs intermediate results the same way. If you think of it from the programming problem perspective this is obvious: in order to refactor VS C++ you have to be able to compile C++ the exact same way VS does with the same bugs, limitations, flaws, hacks, shortcuts, workarounds, etc. The usual suspects like Coderush and Resharper do not have the budget for that kind of insanity although apparently they are trying but it has been years...
http://www.jetbrains.com/resharper-cpp/
Update 2016: Resharper now does a decent job at C++ refactor. Limitations are purely for large / gigantic projects.
MS has finally done this: https://channel9.msdn.com/Shows/C9-GoingNative/GoingNative-33-C-Refactoring-in-Visual-Studio-2015#time=04m37s
They have started doing this about 10 years ago, I remember watching ms channel9 long ago.
I've been using Visual Assist X with visual studio for about one year and a half. It's an incredible tool that helps you a lot with ordinary C++ code, but it doesn't perform very well on templated code. For instance, you if have a sophisticated policy-based template design, it won't know how to rename your variables, and the project won't compile anymore.
Install plugin which enables you that functionality: https://visualstudiogallery.msdn.microsoft.com/164904b2-3b47-417f-9b6b-fdd35757d194
I'd like to point out that Qt Creator (a C++ IDE which is compatible with VC++ libraries and build system) provides symbol renaming that works very well:
You can rename symbols in all files in a project. When you rename a class, you can also change filenames that match the class name.
Qt Creator - Refactoring: Renaming Symbols
Qt Creator's rename functionality gives you a list of the symbol references it found and an opportunity to exclude any of them before performing the replace. So if it gets a symbol reference wrong, you can exclude it.
So C++ symbol renaming is possible. Coming to VS from Qt Creator I feel your pain, to the point where I've considered converting preexisting VS projects of considerable size to use Qt Creator instead.
I don't buy the argument that this is specifically hard in C++. In addition to the fact that it already works very well in Qt Creator, there's the fact that the compiler and linker can find and match symbols: If that wasn't possible you couldn't build your application.
In fact, languages like Python that are dynamically typed also have renaming tools. If you can create such a tool for a language where there are no explicit references to variable type you can definitely do it for C++.
Case in point:
... Rope, a python refactoring library... I tried it for a few renames, and that definitely worked as expected.
Stack Overflow - What refactoring tools do you use for Python?
Well in spite of comments by all you experts I totally disagree that refactoring support issue has something to do with C++ language semantics or any language semantics for that matter. Except the compiler builder themselves don't choose to implement one in first case due to their own reasons or constraints whatsoever they maybe.
And offense not to be taken but I am sorry to say Mr jsb the above link you provided to support your case (i.e of yosefk) about C++ defect is totally out of question. Its more like you providing direction to "Los angeles" when someone asked for of "San Franisco".
In my opinion raising refactoring difficulty issue for certain language is more like raising a finger on language integrity itself. Especially for languages which is sometimes just pain.... when it comes to their variable declaration and use. :) Okay! tell me how come you loose track of some node within a node tree ... eh? So what it is do with any language be it as simple as machine level code. You know you VS compiler can easily detect if some variable or routine is dead code. Got my point?
About developing third party tool. I think compiler vendors can implement it far more easily and effectively if they ever wanted to then a third party tool which will have to duplicate all the parsing database to handle it. Nowadays compiler can optimize code very efficiently at machine code level and I am hearing here that its difficult to tell how some variable is used previously. You haven't paid any real attention to inner working of compiler I suppose. What database it keep within.
And sure its the almost same database that IDE use for all such similar purposes. In previous time compiler were just a separate entity and IDE just a Text Editor with some specialization but as times goes by the gap between compiler and IDE Editor become less and its directly started working on similar parsed database. Which makes it possible to handle all those intellisense and refactoring or other syntax related issues more effectively. With all precompile things and JIT compiling this gap is almost negligent. So it almost make sense to use same database for both purpose or else your memory demand go higher due to duplication.
You all are programmers - I am not! And you guys seems to be having difficulty visualizing how refactoring can be implemented for C++ or any language that I can't comprehend. Its just all about for something you have to put more effort for some less depending on how heavy is a person you trying push.
Anyway way VS a nice IDE especially when it comes to C#.