Doxygen is not documentation
-
The code is the urtext, and its documentation is a derivative work to help readers understand it. Cluttering and defiling it with tags to the point where it has to be exported by a tool is an abomination. X| :mad:
Robust Services Core | Software Techniques for Lemmings | Articles
The fox knows many things, but the hedgehog knows one big thing.Agreed. I have an intense dislike for over-commenting. I'll quote something Dan Saks, one-time Secretary of the ANSI/ISO C++ Standard Committee, said in a C++ class he taught at my employer: "If at all possible, say it in code. Otherwise, say it in a comment." I've followed this advice ever since. Careful naming eliminates most of the "what is this?" sort of comments that a lot of people write. If I'm implementing a specific algorithm or to a particular specification, I'll include that information in a comment. I despise text-mode graphic comments with cutesy graphics or anything of that crap. The only exceptions are I do occasionally use 'dividers' like this:
// ------------------------------------------------------------------------------
// Heading text
// ------------------------------------------------------------------------------to partition logical sections of the code or declarations. We also have a change list tool as part of our automatic build process that constructs a change history correlated by version based upon comments in the source code.
Software Zen:
delete this; -
:elephant: :elephant: :elephant: :elephant: :elephant: :elephant:ing devs who rename their Doxygen :sunshine: as documentation and call it a day. Now I know precisely what public members your library defines (reading the code is out of fashion) and nothing at all on how the :elephant: I am supposed to use it. :mad::mad::mad:
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
-
I don't mind headers, as long as they are sensible - I use spacing comments a lot and a small header works just fine. i.e. something like this is fine for me (about the max size I can tolerate for a header)
/**
* Function: connectionIsValid
* Description: returns TRUE if the address of the client is acceptable
* Arguments:
* connectedClient: pointer to the sockaddr returned by accept()
* structLen: lenght of sockaddr returned by accept()
* Return:
* duo_bool_t TRUE if connection is accepted, FALSE if not.
*/They are just an embellishment of a comment though, documentation is another thing entirely.
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
-
I've been called out in meetings and *thanked* for writing comments. We have a fairly high turnover rate where I work, and knowing that, I comment pretty much everything I do, not so much as the "what", but more the "why" of code. I also comment as if the person coming in behind me is fairly new at being a programmer. I've actually gotten letters of commendation for my "drive towards more maintainable code". Good comments are worth the effort and the clutter that necessarily comes with them. We don't use Doxygen,
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013 -
I've been called out in meetings and *thanked* for writing comments. We have a fairly high turnover rate where I work, and knowing that, I comment pretty much everything I do, not so much as the "what", but more the "why" of code. I also comment as if the person coming in behind me is fairly new at being a programmer. I've actually gotten letters of commendation for my "drive towards more maintainable code". Good comments are worth the effort and the clutter that necessarily comes with them. We don't use Doxygen,
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013 -
I don't mind headers, as long as they are sensible - I use spacing comments a lot and a small header works just fine. i.e. something like this is fine for me (about the max size I can tolerate for a header)
/**
* Function: connectionIsValid
* Description: returns TRUE if the address of the client is acceptable
* Arguments:
* connectedClient: pointer to the sockaddr returned by accept()
* structLen: lenght of sockaddr returned by accept()
* Return:
* duo_bool_t TRUE if connection is accepted, FALSE if not.
*/They are just an embellishment of a comment though, documentation is another thing entirely.
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
I do not believe that function needs any documentation as the names of the function and arguments are self explanatory as they should be
-
I don't mind headers, as long as they are sensible - I use spacing comments a lot and a small header works just fine. i.e. something like this is fine for me (about the max size I can tolerate for a header)
/**
* Function: connectionIsValid
* Description: returns TRUE if the address of the client is acceptable
* Arguments:
* connectedClient: pointer to the sockaddr returned by accept()
* structLen: lenght of sockaddr returned by accept()
* Return:
* duo_bool_t TRUE if connection is accepted, FALSE if not.
*/They are just an embellishment of a comment though, documentation is another thing entirely.
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
I do not believe that function needs any documentation as the function name and argument names are self explanatory as they should be. In my own work I rarely document for that reason. Also I am lazy
-
:elephant: :elephant: :elephant: :elephant: :elephant: :elephant:ing devs who rename their Doxygen :sunshine: as documentation and call it a day. Now I know precisely what public members your library defines (reading the code is out of fashion) and nothing at all on how the :elephant: I am supposed to use it. :mad::mad::mad:
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
Doxygen was documentation in the 1990s, before your IDE could show you all the classes in your project, and you had to have paper documentation. Not so much today. Doxygen is not documentation if you don't use Doxygen comments to at least say what function args mean, but rely exclusively upon what Doxygen finds by itself, again because your IDE already does that.
-
Perhaps, now you have some influence, you can convince your employer and team to use Doxygen -- take your code to the next level. :cool::java:
~d~
I'm a contractor. I have no influence.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013 -
Yeah, I don't care for that stuff, because to me it increases maintenance without (usually) adding much value beyond the description. I tend to lean on long, descriptive parameter names and hard typing everything I need to be as descriptive as possible, even if means using a bool instead of an int like a lot of people do. =)
Real programmers use butterflies
Indeed. Good names and taking advantage of C++'s strong typing is good enough a documentation for 90% of all functions. I've often seen hard to read code that could be improved just by using appropriate names and the correct data types.
intis overused - I've seen too many cases whereboolorenums would be a much better fit, and increase readability too.GOTOs are a bit like wire coat hangers: they tend to breed in the darkness, such that where there once were few, eventually there are many, and the program's architecture collapses beneath them. (Fran Poretto)
-
:elephant: :elephant: :elephant: :elephant: :elephant: :elephant:ing devs who rename their Doxygen :sunshine: as documentation and call it a day. Now I know precisely what public members your library defines (reading the code is out of fashion) and nothing at all on how the :elephant: I am supposed to use it. :mad::mad::mad:
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
The problem isn't doxygen, the problem is people thinking that using such a tool creates useful documentation all by itself. If you can't come up with sensible comments at the right places, sensible function and variable names, and clean code, then no tool in the world will magically turn that code into well documented code!
GOTOs are a bit like wire coat hangers: they tend to breed in the darkness, such that where there once were few, eventually there are many, and the program's architecture collapses beneath them. (Fran Poretto)
-
Amen. I nix'd using Doxygen for that very reason -- a screenful of tags for a 5 line function. It makes visually scanning the codebase a nightmare. Better to just document stuff in a separate file -- wiki, markdown, HTML, Word doc, whatever.
Latest Articles:
Client-Side Type-Based Publisher/Subscriber, Exploring Synchronous, "Event-ed", and Worker Thread SubscriptionsDoxygen is fine - its actually a great way of automatically annotating code to make a hyperlinked bundle that you can explore in a web browser. However, insisting on commenting every single class, method and parameter is certainly a waste of time IMHO when self-documenting code is in play (as it should be).
-
Amen. I nix'd using Doxygen for that very reason -- a screenful of tags for a 5 line function. It makes visually scanning the codebase a nightmare. Better to just document stuff in a separate file -- wiki, markdown, HTML, Word doc, whatever.
Latest Articles:
Client-Side Type-Based Publisher/Subscriber, Exploring Synchronous, "Event-ed", and Worker Thread SubscriptionsYES TO THIS. All of my this.
Real programmers use butterflies
-
The problem isn't doxygen, the problem is people thinking that using such a tool creates useful documentation all by itself. If you can't come up with sensible comments at the right places, sensible function and variable names, and clean code, then no tool in the world will magically turn that code into well documented code!
GOTOs are a bit like wire coat hangers: they tend to breed in the darkness, such that where there once were few, eventually there are many, and the program's architecture collapses beneath them. (Fran Poretto)
Stefan_Lang wrote:
The problem isn't doxygen, the problem is people
I never blame the tool, only the people using it (except if the tool doesn't work properly, but Doxygen does).
GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
