Click here to Skip to main content
15,878,035 members

Welcome to the Lounge

   

For discussing anything related to a software developer's life but is not for programming questions. Got a programming question?

The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.

 
GeneralRe: Code comments - how old is your code? Pin
Slacker00717-Jul-23 12:23
professionalSlacker00717-Jul-23 12:23 
GeneralRe: Code comments - how old is your code? Pin
Gary R. Wheeler17-Jul-23 13:17
Gary R. Wheeler17-Jul-23 13:17 
GeneralRe: Code comments - how old is your code? Pin
Slacker00717-Jul-23 13:33
professionalSlacker00717-Jul-23 13:33 
GeneralRe: Code comments - how old is your code? Pin
Matt Bond18-Jul-23 3:26
Matt Bond18-Jul-23 3:26 
GeneralRe: Code comments - how old is your code? Pin
Gerry Schmitz18-Jul-23 5:33
mveGerry Schmitz18-Jul-23 5:33 
GeneralRe: Code comments - how old is your code? Pin
Mircea Neacsu17-Jul-23 14:52
Mircea Neacsu17-Jul-23 14:52 
GeneralRe: Code comments - how old is your code? Pin
Greg Utas17-Jul-23 15:35
professionalGreg Utas17-Jul-23 15:35 
GeneralRe: Code comments - how old is your code? Pin
trønderen17-Jul-23 16:16
trønderen17-Jul-23 16:16 
I am perfectly in agreement with you.
Greg Utas wrote:
I have absolutely no tolerance for markup noise in comments, like Doxygen
I have the impression that this is becoming more and more the standard practice - it may be a different system from Doxygen, but the principles are the same.

Let me extend it to lint comments. A few years ago, I cleaned up a code base that was soaked with lint comments to suppress specific lint warnings, yet a complete system build returned more that 23,000 lint errors and warnings. The developers were so used to seeing hundreds of them even for small unit compilations that they overlooked the warnings. Every now and then they made 'cleanups', which amounted to adding even more lint comments to reduce the number of warnings in the unit that was their responsibility.

I set out to define a lintfile that would globally suppress the warnings we defined as ignorable, and for the remaining ones, modify the code so lint kept quiet. (We also redefined a number of warnings as errors, failing the build.) The source code became a lot more readable with all those lint comments out of it!

I earlier worked with a company using/writing open source code: The coding rules required that a .c file contains a single function only. Common practice was to write very small functions, with bodies typically in the range of 5 to 20 lines. The problem was to see the code, you had to page down to the third screenful: Every file had to include an extensive copyleft / license statement. This caused the code base to have 80% comment lines.

I very much like the statement made by Gary R. Wheeler, above: "If it can be said in code, say it in code. Otherwise say it in a comment." Whether it is intended for a documentation system (such as Doxygen) or just because company standard requires it, I see lots of function header comments that copies the function name, argument list a comment, with type/class and all. In most cases, the 'explanation' is nothing more than expanding a quite self-documenting name to a sequence of words, like 'int numberOfApples -- integer number of apples'. Or a fuction named 'CalculateTheTotalBill' providing an explanation 'This function calculates the total bill'. If you don't have anyting to say, don't say it!

I would like to add to Wheeler's statement: "The primary purpose of the code is to show WHAT is done. The primary purpose of a comment is to explain WHY it is done."
GeneralRe: Code comments - how old is your code? Pin
Gerry Schmitz18-Jul-23 5:39
mveGerry Schmitz18-Jul-23 5:39 
GeneralRe: Code comments - how old is your code? Pin
Gary Wheeler18-Jul-23 2:39
Gary Wheeler18-Jul-23 2:39 
GeneralRe: Code comments - how old is your code? Pin
Gerry Schmitz17-Jul-23 15:36
mveGerry Schmitz17-Jul-23 15:36 
GeneralRe: Code comments - how old is your code? Pin
Derek Hunter17-Jul-23 20:14
Derek Hunter17-Jul-23 20:14 
GeneralRe: Code comments - how old is your code? Pin
Jonas Hammarberg17-Jul-23 20:49
professionalJonas Hammarberg17-Jul-23 20:49 
GeneralRe: Code comments - how old is your code? Pin
Sander Rossel17-Jul-23 21:02
professionalSander Rossel17-Jul-23 21:02 
GeneralRe: Code comments - how old is your code? Pin
Slacker00717-Jul-23 23:40
professionalSlacker00717-Jul-23 23:40 
GeneralRe: Code comments - how old is your code? Pin
Sander Rossel17-Jul-23 23:43
professionalSander Rossel17-Jul-23 23:43 
JokeRe: Code comments - how old is your code? Pin
trønderen18-Jul-23 6:49
trønderen18-Jul-23 6:49 
GeneralRe: Code comments - how old is your code? Pin
Gerry Schmitz18-Jul-23 5:43
mveGerry Schmitz18-Jul-23 5:43 
GeneralRe: Code comments - how old is your code? Pin
Amarnath S17-Jul-23 21:06
professionalAmarnath S17-Jul-23 21:06 
GeneralRe: Code comments - how old is your code? Pin
_WinBase_17-Jul-23 23:36
_WinBase_17-Jul-23 23:36 
GeneralRe: Code comments - how old is your code? Pin
Gerry Schmitz18-Jul-23 5:46
mveGerry Schmitz18-Jul-23 5:46 
GeneralRe: Code comments - how old is your code? Pin
Mircea Neacsu18-Jul-23 0:51
Mircea Neacsu18-Jul-23 0:51 
GeneralRe: Code comments - how old is your code? Pin
Daniel Pfeffer18-Jul-23 1:04
professionalDaniel Pfeffer18-Jul-23 1:04 
GeneralRe: Code comments - how old is your code? Pin
JudyL_MD18-Jul-23 1:59
JudyL_MD18-Jul-23 1:59 
GeneralRe: Code comments - how old is your code? Pin
decaffeinatedMonkey18-Jul-23 2:41
decaffeinatedMonkey18-Jul-23 2:41 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.