4 years in software engineering and that's what I have learned.

[madires]

Can't speak for others, but I update comments when I change the code.

[tggzzz]

Can't speak for others, but I update comments when I change the code.

How.... unusually considerate

[Siwastaja]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

[coppice]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

[tggzzz]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

Just so. Not a difficult concept.

Given a thoughtful architecture, Changes at that level ought to be rare.

But architecture is so unfashionable nowadays. Instead, good properties just emerge.from the bottom up.

Don't they?

[Siwastaja]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

And I have said this before, but a simple observation: projects that use doxygen are usually the worst. Maybe just coincidence, but the false sense of getting some variable list automagically generated and updated gives that nice feeling that the job is done. But of course it isn't, autogenerated boilerplate is the unnecessary part, this is visible from the declaration itself. Human is needed to carefully think about how the function would be used, and write a concise yet accurate enough description of each argument, and this work can only be maintained manually.

[coppice]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

And I have said this before, but a simple observation: projects that use doxygen are usually the worst. Maybe just coincidence, but the false sense of getting some variable list automagically generated and updated gives that nice feeling that the job is done. But of course it isn't, autogenerated boilerplate is the unnecessary part, this is visible from the declaration itself. Human is needed to carefully think about how the function would be used, and write a concise yet accurate enough description of each argument, and this work can only be maintained manually.

Almost all helpful tools are a two edged sword. On the one hand they help the careful towards a clean result. On the other they encourage those who wouldn't give a shit to continue to withhold them.

[tggzzz]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

And I have said this before, but a simple observation: projects that use doxygen are usually the worst. Maybe just coincidence, but the false sense of getting some variable list automagically generated and updated gives that nice feeling that the job is done. But of course it isn't, autogenerated boilerplate is the unnecessary part, this is visible from the declaration itself. Human is needed to carefully think about how the function would be used, and write a concise yet accurate enough description of each argument, and this work can only be maintained manually.

Almost all helpful tools are a two edged sword. On the one hand they help the careful towards a clean result. On the other they encourage those who wouldn't give a shit to continue to withhold them.

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

[coppice]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

And I have said this before, but a simple observation: projects that use doxygen are usually the worst. Maybe just coincidence, but the false sense of getting some variable list automagically generated and updated gives that nice feeling that the job is done. But of course it isn't, autogenerated boilerplate is the unnecessary part, this is visible from the declaration itself. Human is needed to carefully think about how the function would be used, and write a concise yet accurate enough description of each argument, and this work can only be maintained manually.

Almost all helpful tools are a two edged sword. On the one hand they help the careful towards a clean result. On the other they encourage those who wouldn't give a shit to continue to withhold them.

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

Correct, and your point it?

[Siwastaja]

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

Yes, and my observation is this: people are taught to be afraid of modifying generated code/text, which makes a lot of sense, because in many cases you definitely should not be doing that (e.g., generated coefficient tables; modify the source which generates the tables instead).

And yet, for Doxygen it's the exact opposite: you get a tiny bit of boilerplate, and totally should add as much relevant content as possible. I believe that this boilerplate is however directing people to either not touch it at all (I have seen this!) or edit it as little as possible, limiting them to add just a few words, especially when they are unsure where exactly to type to produce the correct HTML output.

Sometimes too much formality kills the productivity - in this case comment-writing. Code itself is already limited to certain formal constructs; I don't want my comments to have to do the same, and I don't want to have to memorize another domain specific language for comment processing.

[coppice]

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

Yes, and my observation is this: people are taught to be afraid of modifying generated code/text, which makes a lot of sense, because in many cases you definitely should not be doing that (e.g., generated coefficient tables; modify the source which generates the tables instead).

And yet, for Doxygen it's the exact opposite: you get a tiny bit of boilerplate, and totally should add as much relevant content as possible. I believe that this boilerplate is however directing people to either not touch it at all (I have seen this!) or edit it as little as possible, limiting them to add just a few words, especially when they are unsure where exactly to type to produce the correct HTML output.

Sometimes too much formality kills the productivity - in this case comment-writing. Code itself is already limited to certain formal constructs; I don't want my comments to have to do the same, and I don't want to have to memorize another domain specific language for comment processing.

Do people do a lot of automatic generation for doxygen? That destroys all its benefits. No wonder you don't like it. The big plus is when you modify code, if you haven't modified the doxygen comments to match, say, new defines or call parameters, it flags up the mismatches. That doesn't help where only the meaning of a parameter has changed, without changing its name. It doesn't help when your comments suck. However, it does catch a lot.

[tggzzz]

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

Yes, and my observation is this: people are taught to be afraid of modifying generated code/text, which makes a lot of sense, because in many cases you definitely should not be doing that (e.g., generated coefficient tables; modify the source which generates the tables instead).

And yet, for Doxygen it's the exact opposite: you get a tiny bit of boilerplate, and totally should add as much relevant content as possible. I believe that this boilerplate is however directing people to either not touch it at all (I have seen this!) or edit it as little as possible, limiting them to add just a few words, especially when they are unsure where exactly to type to produce the correct HTML output.

Sometimes too much formality kills the productivity - in this case comment-writing. Code itself is already limited to certain formal constructs; I don't want my comments to have to do the same, and I don't want to have to memorize another domain specific language for comment processing.

Do people do a lot of automatic generation for doxygen? That destroys all its benefits. No wonder you don't like it.

Too many do, hence my comment

But it ticks the "documentation delivered" box.

Doesn't it?

[coppice]

Automagically generated boilerplate cannot contain any new information, i.e. information not in the source.

Yes, and my observation is this: people are taught to be afraid of modifying generated code/text, which makes a lot of sense, because in many cases you definitely should not be doing that (e.g., generated coefficient tables; modify the source which generates the tables instead).

And yet, for Doxygen it's the exact opposite: you get a tiny bit of boilerplate, and totally should add as much relevant content as possible. I believe that this boilerplate is however directing people to either not touch it at all (I have seen this!) or edit it as little as possible, limiting them to add just a few words, especially when they are unsure where exactly to type to produce the correct HTML output.

Sometimes too much formality kills the productivity - in this case comment-writing. Code itself is already limited to certain formal constructs; I don't want my comments to have to do the same, and I don't want to have to memorize another domain specific language for comment processing.

Do people do a lot of automatic generation for doxygen? That destroys all its benefits. No wonder you don't like it.

Too many do, hence my comment

But it ticks the "documentation completed" box. Doesn't it?

As I said, give people any good tool, and some will be more effective while others feed their inner idle scumbag.

[nctnico]

That's the main reason why I write many comments in my code, helping me to maintain it later on.

We have discussed this many times, but once again I'll say this: the most useful comments are:
* those large 50-100-line walls of text at the beginning of every module, describing what it is supposed to do, and how it interacts with other modules
* comments in header files that describe what the functions actually do, and their inputs and outputs quite accurately (e.g.; does the caller need to keep *arg allocated still after the call?)

Of course keeping them in sync with the code is a lot of work; concentrating on the big picture helps in that small discrepancies are not catastrophic since the main intent keeps the same, and such broad comments save hours of time when one looks at a new codebase, trying to figure out what interacts with what.

If you use the right tools, a lot of the discrepancies between the description of a function and any updates to actual parameters, return values, etc. over time get flagged for correction. That is a huge plus for things like doxygen.

And I have said this before, but a simple observation: projects that use doxygen are usually the worst. Maybe just coincidence, but the false sense of getting some variable list automagically generated and updated gives that nice feeling that the job is done. But of course it isn't, autogenerated boilerplate is the unnecessary part, this is visible from the declaration itself. Human is needed to carefully think about how the function would be used, and write a concise yet accurate enough description of each argument, and this work can only be maintained manually.

I couldn't agree more. 100 out of 100 times the Doxygen created rubbish is useless. I do read it in case there is a hidden gem there but spotting one hasn't happened to me. I think collecting the pot of gold at the end of a rainbow is a more worthwhile effort. A modern day IDE provides the exact same information and it is updated in realtime.  I always hope the creator of a piece of code wrote a bit of text together with the source code to find out what a module is supposed to do. Sometimes I get lucky.

[pdenisowski]

The solution to comments being out of date is to strip out all comments and just read the (very clear and precise) code.

I heard the term "self-documenting code" used unironically many, many times

[SiliconWizard]

Doxygen relies on comments formatted in a very specific way to be of any use. So if one doesn't think comments are ever up to date, Doxygen doc will never be either. All it does automatically is extract definitions, so your data structures and function prototypes will match the source code, but the documentation for parameters or what the functions actually do may never be.

It can be useful for documenting APIs (as long as you keep corresponding comments up to date). But for otherwise documenting a whole code base, not that much.

It does extract call graphs, but you can get that with other tools too.

[nctnico]

Doxygen relies on comments formatted in a very specific way to be of any use. So if one doesn't think comments are ever up to date, Doxygen doc will never be either. All it does automatically is extract definitions, so your data structures and function prototypes will match the source code, but the documentation for parameters or what the functions actually do may never be.

It can be useful for documenting APIs (as long as you keep corresponding comments up to date). But for otherwise documenting a whole code base, not that much.

Nope. API documentation should provide you with information about how to use the function calls together. How to make a coherent solution. Doxygen generated crap is like giving someone a random list of ingredients and expect to cook an extensive meal from it without specifying which ingredients go together in a dish, which dishes of the meal must be baked, what must be cooked and what has to be served cold.

[janoc]

Doxygen relies on comments formatted in a very specific way to be of any use. So if one doesn't think comments are ever up to date, Doxygen doc will never be either. All it does automatically is extract definitions, so your data structures and function prototypes will match the source code, but the documentation for parameters or what the functions actually do may never be.

It can be useful for documenting APIs (as long as you keep corresponding comments up to date). But for otherwise documenting a whole code base, not that much.

Nope. API documentation should provide you with information about how to use the function calls together. How to make a coherent solution. Doxygen generated crap is like giving someone a random list of ingredients and expect to cook an extensive meal from it without specifying which ingredients go together in a dish, which dishes of the meal must be baked, what must be cooked and what has to be served cold.

That only holds if Doxygen generated from sources with no comments is the only documentation. But that's hardly Doxygen's fault, is it?

If used properly it is a valuable tool, esp. on large projects. But as with anything - garbage in, garbage out. If your team can't be bothered to describe the functions/datastructures, can't be bothered to write high level documentation explaining the use the APIs, etc. then autogenerated reference documentation from Doxygen is not going to save the day either.

That Doxygen (and similar tools) are frequently used only to check the "Provide documentation" checkbox on the TODO list with minimal effort possible is not really the fault of the tool.

The solution to comments being out of date is to strip out all comments and just read the (very clear and precise) code.

I heard the term "self-documenting code" used unironically many, many times

That's just BS. Yes, code should be ideally "self-documenting". But that's not an excuse to not have documentation - that code should be readable and easy to understand is a completely orthogonal concept to having high level/reference documentation for the codebase. Both things need to be in place if you want to have any sort of chance to work on a large codebase efficiently.

Good luck having to wade through millions of lines of source code to figure out how to use a certain feature. Having it documented at least at the high level is a huge time saver. I am working on codebase that is 25+ years old, millions of lines, some very complex. With very little documentation - I can tell you, it is a huge "fun" having to reverse engineer that stuff whenever I need to add a button somewhere. Just finding the right place where to start working is a challenge already. Yes, documentation can go stale - but even outdated documentation for concepts that are still being used in the codebase is better than having nothing - it gives you at least a starting point.

The same if you see some complex algorithm or the reasons why a seemingly arbitrary decision was made is not obvious. Think e.g. physics simulation or some complex event handling or working around some platform issue ... Having a comment in the code for your colleagues (or even the future you) linking in e.g. the JIRA ticket requesting the change or some explanation of what is going on is essential. Yes, comments can get outdated - but that's your job when you modify that code in the future to also fix the comment, if needed. That the team is lacking the discipline to do this is not really a good reason to not write useful comments or documentation.

I have seen so much code engineered using this "self-documenting code" mantra - broken down into hundreds of tiny ("self-documenting") functions that are then haphazardly assembled together in a huge spaghetti mess with no clear idea of why, what depends on what, requiring to reverse engineer the architecture of this mess each time, making any sort of maintenance a costly nightmare.

Worse, usually the codebase knowledge is only in the heads of some old-timers in the company. Suddenly they get laid off or leave on their own and you are back to square one, because nobody has any idea how a certain feature or code works. Such things could even cause a company go bankrupt in extreme cases - or at least give the laid off people a very cushy and well paid consulting job while the know-how is transferred ...

Yes, and my observation is this: people are taught to be afraid of modifying generated code/text, which makes a lot of sense, because in many cases you definitely should not be doing that (e.g., generated coefficient tables; modify the source which generates the tables instead).

And yet, for Doxygen it's the exact opposite: you get a tiny bit of boilerplate, and totally should add as much relevant content as possible. I believe that this boilerplate is however directing people to either not touch it at all (I have seen this!) or edit it as little as possible, limiting them to add just a few words, especially when they are unsure where exactly to type to produce the correct HTML output.

But you don't modify the generated content. You modify either your code and put the documentation there in the comments that Doxygen then extracts. Or you modify the templates the generator uses, e.g. to include some static content.

BTW, for documenting code in the format that Doxygen (or Javadoc or Python Sphinx, etc.) understands there are plenty of tools - there are even plugins for VS Code and similar editors that will automatically extract the function signatures and generate/update the entire boilerplate of the comment for you. You only need to fill in the meaning of all those arguments, what the function returns and some description of what the function does. A lot of "Intellisense"-like tools will also use these comments and display the information right during completion in the editor, so that you have immediately an idea what is which argument doing without having to look it up.

This functionality and tooling exists since ages (and is only getting better). I am rather surprised that it is not known and people think they have to manually do this. There are even tools that will generate these comments for your entire codebase, if you so wish - I personally wouldn't do that but the option is there.

https://marketplace.visualstudio.com/search?term=doxygen&target=VSCode&category=Other&sortBy=Relevance

[DiTBho]

It does extract call graphs, but you can get that with other tools too.

SciTools Understand 

[tggzzz]

Doxygen relies on comments formatted in a very specific way to be of any use. So if one doesn't think comments are ever up to date, Doxygen doc will never be either. All it does automatically is extract definitions, so your data structures and function prototypes will match the source code, but the documentation for parameters or what the functions actually do may never be.

It can be useful for documenting APIs (as long as you keep corresponding comments up to date). But for otherwise documenting a whole code base, not that much.

Nope. API documentation should provide you with information about how to use the function calls together. How to make a coherent solution. Doxygen generated crap is like giving someone a random list of ingredients and expect to cook an extensive meal from it without specifying which ingredients go together in a dish, which dishes of the meal must be baked, what must be cooked and what has to be served cold.

Not a bad analogy

[Siwastaja]

But you don't modify the generated content.

I was unclear. I did not mean modifying the HTML output (for example). What I meant is: almost always an IDE is used to generate the boilerplate (in the Doxygen DSL) within the comments. This boilerplate has to be then modified (basically information added in the middle of it). It is tempting to forget filling in that information completely, or be very concise.

Unlike in normal programming languages where the whole code is supposed to serve both compiler and human reader (at least in the ideal world), Doxygen DSL boilerplate only serves the Doxygen compiler and often hinders the human who modifies it. Not always of course, and you can put the blame to the user if you so wish.

[pdenisowski]

I heard the term "self-documenting code" used unironically many, many times

That's just BS.

Indeed it is   I'm still amazed at how many people said that to me with a straight face.

Good luck having to wade through millions of lines of source code to figure out how to use a certain feature. Having it documented at least at the high level is a huge time saver. I am working on codebase that is 25+ years old, millions of lines, some very complex. With very little documentation

You also worked on DMS100 software (BCS) at Nortel ?!?!  Wow, small world.

Edit:  I forgot to add that it has to be a proprietary variant of a dead programming language (Pascal) where having an infinite loop with a break statement is considered normal coding practice 

[coppice]

The solution to comments being out of date is to strip out all comments and just read the (very clear and precise) code.

I heard the term "self-documenting code" used unironically many, many times

Its not exactly a stupid term, but it tends to be received in a stupid way by the lazy. If you think that having variables i and j is just as good as meaningful names (other than elementary cases like loop variables) you shouldn't be in programming. At that sort of level code should self-document. As well as people hand waving the stupid idea of their code being fully self-documenting there are people who write extensive comments to explain what their obscurely named variables do, instead of choosing better names. Balanced is a big part of good practice in any kind of engineering. You need to put your resources where they get the most bang per buck.

[DiTBho]

If you think that having variables i and j is just as good as meaningful names (other than elementary cases like loop variables) you shouldn't be in programming. At that sort of level code should self-document

This sounds a lot like a comment i got in my letterbox a while back from an anonymous person who said "you should get a job at McDonald's, coding is not for you" 

I usually use { i0, i1, i2, i3 ... } for my loop variables as for the indices of matrices and tensors, with approximately the same notation used in mathematics, and not only it's perfectly fine, but also *VERY* useful for the ICE, since I need the shorted names possible on a session, plus, postfixing 0,1,2,3,4 ... helps the text editor I wrote it myself to rename, search, and move amoung observable variables.

Code: [Select]

private boolean_t do_l2_scan
(
    p_dep_man_t p_dep_man
)
{
    my_id_t            fid;
    boolean_t          ans;
    p_bitmatrix_t      p_matrix0;
    p_stack_dep_data_t p_data;
    uint32_t           i1; /* irow */
    uint32_t           i0; /* icol */
    uint32_t           iblock;
    uint32_t           item_n;
    boolean_t          cell;
    boolean_t          is_EOL;
    boolean_t          is_recursive_call;

    p_matrix0 = p_dep_man->context.matrix.adjacency;
    p_data    = get_address(p_dep_man->context.fsm.data);
    item_n    = p_matrix0->row_n;
    i0        = p_data->i0;

    is_recursive_call = False;
    is_EOL            = False;

    debug_fsm_show(p_dep_man, "scan");

    switch (p_dep_man->context.fsm.status)
    {
    case s0:
    case s2:
        i0     = p_data->i0;
        i1     = p_data->i1;
        iblock = bitmatrix_iblock_get(p_matrix0, i1, i0);
        cell   = bitmatrix_cell_get(p_matrix0, iblock);
        if (cell)
        {
        ...

As you see people are not as stupid as you might think with your superficial way of judging others.
Which I find extremely arrogant, among other things

But, let me understand would you use the last offensive term you recently use in the other topic and call people "dumb moron" for this?

You should be more polite and more tolerant of mistakes, both presumed by you and real mistakes.

[janoc]

You also worked on DMS100 software (BCS) at Nortel ?!?!  Wow, small world.

Edit:  I forgot to add that it has to be a proprietary variant of a dead programming language (Pascal) where having an infinite loop with a break statement is considered normal coding practice 

Oh dear, no, I haven't had the pleasure. Good to know which place to avoid 

But I am pretty sure that the employers of quite a few people on this forum are using our software to inspect parts and assemblies 

I can't complain about coding standard in our codebase too much, it is actually pretty good overall - but with the 25+ years legacy of C++ code and the sheer size, finding one's way around is a major challenge, esp. when the part you need to work on isn't documented.

Or when the "guru" that understood that codebase has just left the company. Have you ever tried to reverse engineer a heavily hand-optimized finite element solver? We have some code like that - and pray that we won't have to go fix something in there ...