4 ms·

I find it interesting how controversial the code comments situation has become. When I started in this industry, comments were extremely rare and people were c

I find it interesting how controversial the code comments situation has become. When I started in this industry, comments were extremely rare and people were consistently pushing to add comments everywhere. Some time later, the pushback came and people started saying that code shouldn't need comments, and if you feel the need to add one... You should rewrite it instead so the code is self explanatory. Neither side seems to have stopped repeating their points though and there is always a chance to trigger opinionated people into endless discussions just by mentioning comments

ChrisMarshallNY 5y ago
I don't bother trying to convince people to see things my way. All I can say, is that I almost never get questions about my code. I write about my approach here: https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ It's a long screed, so no one reads it.
- RobertKerans 5y ago
  It was a good screed, not tedious! It made a lot of sense, thank you.
dec0dedab0de 5y ago
One big thing that has changed in regard to comments is that variables and functions can have longer names now. In most modern languages it is considered bad practice to have single letter variables, or even abbreviated ones, except in very well known cases. So the rule of thumb for languages like python or ruby is that if you need comments to understand what your code is doing, then you messed up somewhere. Make it easier to read, keep your functions small, and add docstrings. Save your comments for why you're doing something. But if you're using a less readable language like c, then by all means, comment everything along the way. I just read a comment I wrote a few years ago that said "I don't know why I have to do it the long way, but it's the only thing that works consistently" over a bit of seemingly verbose code that I would have tried to simplify if I didn't remind myself of that previous struggle.
- Stratoscope 5y ago
  In the previous century I worked at a company that offered a SQL database, and the mandatory coding standard included: - Maximum of six characters for any function name. Three characters for the category and three for the actual function. Imagine a code base where every function has a name like strcmp, strlen, etc. So you might have a name like sqlijn for an inner join. - 80 column line limit, with the first 40 columns reserved for code, and the second 40 columns for a comment. A comment was required on every line of code. So yes indeed, you might see this classic: ++i; /* increment i */ I was hired to build a Windows GUI for the database, and I explained that Windows API functions had much longer names and I was going to run out of room to do much in 40 columns. Thankfully, they gave me special dispensation to follow Windows conventions in the Windows code.
  - ChrisMarshallNY 5y ago
    My function/method/property/variable names can be quite long. Most of my documentation is headerdoc-style stuff, at the opening of methods, or above properties. I generally don't have much inside methods, unless I think the code is a bit obtuse, and needs a hand. Then, it's more important for me to document "why," as opposed to "what."
da39a3ee 5y ago
The trouble with comments is that good taste as well as intelligence is required of the comment author. If you cast your mind over your colleagues you see the problem.

ChrisMarshallNY 5y ago

I don't bother trying to convince people to see things my way. All I can say, is that I almost never get questions about my code. I write about my approach here: https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ It's a long screed, so no one reads it.

RobertKerans 5y ago
It was a good screed, not tedious! It made a lot of sense, thank you.

dec0dedab0de 5y ago

One big thing that has changed in regard to comments is that variables and functions can have longer names now. In most modern languages it is considered bad practice to have single letter variables, or even abbreviated ones, except in very well known cases. So the rule of thumb for languages like python or ruby is that if you need comments to understand what your code is doing, then you messed up somewhere. Make it easier to read, keep your functions small, and add docstrings. Save your comments for why you're doing something. But if you're using a less readable language like c, then by all means, comment everything along the way. I just read a comment I wrote a few years ago that said "I don't know why I have to do it the long way, but it's the only thing that works consistently" over a bit of seemingly verbose code that I would have tried to simplify if I didn't remind myself of that previous struggle.

Stratoscope 5y ago
In the previous century I worked at a company that offered a SQL database, and the mandatory coding standard included: - Maximum of six characters for any function name. Three characters for the category and three for the actual function. Imagine a code base where every function has a name like strcmp, strlen, etc. So you might have a name like sqlijn for an inner join. - 80 column line limit, with the first 40 columns reserved for code, and the second 40 columns for a comment. A comment was required on every line of code. So yes indeed, you might see this classic: ++i; /* increment i */ I was hired to build a Windows GUI for the database, and I explained that Windows API functions had much longer names and I was going to run out of room to do much in 40 columns. Thankfully, they gave me special dispensation to follow Windows conventions in the Windows code.
- ChrisMarshallNY 5y ago
  My function/method/property/variable names can be quite long. Most of my documentation is headerdoc-style stuff, at the opening of methods, or above properties. I generally don't have much inside methods, unless I think the code is a bit obtuse, and needs a hand. Then, it's more important for me to document "why," as opposed to "what."

da39a3ee 5y ago

The trouble with comments is that good taste as well as intelligence is required of the comment author. If you cast your mind over your colleagues you see the problem.