Commenting Style Preference

This is a discussion on Commenting Style Preference within the C++ Programming forums, part of the General Programming Boards category; Quick: with javadoc style comments, document the header or the implementation?...

  1. #1
    Registered User
    Join Date
    Aug 2003
    Posts
    35

    Commenting Style Preference

    Quick: with javadoc style comments, document the header or the implementation?
    you make me rery ascared

  2. #2
    Toaster Zach L.'s Avatar
    Join Date
    Aug 2001
    Posts
    2,686
    I usually prefer documenting the header more extensively.
    The word rap as it applies to music is the result of a peculiar phonological rule which has stripped the word of its initial voiceless velar stop.

  3. #3
    Registered User
    Join Date
    Dec 2004
    Location
    UK
    Posts
    109
    One of the idaes behind the header/source separation is that you can distribute the headers without giving away your code. That means is that the headers are the only part of your program most people will ever see (and in fact the only part they should need to see). Comments that are not there are useless to anyone but you.

  4. #4
    Registered User
    Join Date
    Jan 2002
    Location
    Vancouver
    Posts
    2,220
    I usually comment above functions indicating their purpose, and inside the functions to let you know what's going on at hard to read places.

  5. #5
    Registered User major_small's Avatar
    Join Date
    May 2003
    Posts
    2,787
    usually I comment every line I can... even on simple 2+2 statements.

    I also don't normally comment while writing. I finish a function and then go back and write the comment and/or documentation, because it gets in the way sometimes...
    Last edited by major_small; 12-09-2004 at 06:35 AM.
    Join is in our Unofficial Cprog IRC channel
    Server: irc.phoenixradio.org
    Channel: #Tech


    Team Cprog Folding@Home: Team #43476
    Download it Here
    Detailed Stats Here
    More Detailed Stats
    52 Members so far, are YOU a member?
    Current team score: 1223226 (ranked 374 of 45152)

    The CBoard team is doing better than 99.16% of the other teams
    Top 5 Members: Xterria(518175), pianorain(118517), Bennet(64957), JaWiB(55610), alphaoide(44374)

    Last Updated on: Wed, 30 Aug, 2006 @ 2:30 PM EDT

  6. #6
    Cat without Hat CornedBee's Avatar
    Join Date
    Apr 2003
    Posts
    8,892
    usually I comment every line I can... even on simple 2+2 statements.
    [...]
    because it gets in the way sometimes...
    Have you ever thought these two could be related?


    I usually use Doxygen comments only at the start/declaration of every function/class/whatever. Then I might add other comments, which might wrap up a complicated piece of code or explain why I am doing something a particular way.
    All the buzzt!
    CornedBee

    "There is not now, nor has there ever been, nor will there ever be, any programming language in which it is the least bit difficult to write bad code."
    - Flon's Law

  7. #7
    Registered User major_small's Avatar
    Join Date
    May 2003
    Posts
    2,787
    Quote Originally Posted by CornedBee
    Have you ever thought these two could be related?
    you think I don't know that? maybe that could be why I don't start commenting until I have a working block of code?

    I comment everything because if I come back to it, I want to be able to know what every line does with a glance. I want to know why I added two variables without looking through the source. besides, it's easy enough to strip code of all it's comments if I wanted to debug (which has already been done by the time I comment).

    hell, I can write a program to do that, and then comment that program, and then use that program to strip the comments out of it's own source...
    Join is in our Unofficial Cprog IRC channel
    Server: irc.phoenixradio.org
    Channel: #Tech


    Team Cprog Folding@Home: Team #43476
    Download it Here
    Detailed Stats Here
    More Detailed Stats
    52 Members so far, are YOU a member?
    Current team score: 1223226 (ranked 374 of 45152)

    The CBoard team is doing better than 99.16% of the other teams
    Top 5 Members: Xterria(518175), pianorain(118517), Bennet(64957), JaWiB(55610), alphaoide(44374)

    Last Updated on: Wed, 30 Aug, 2006 @ 2:30 PM EDT

  8. #8
    Cat without Hat CornedBee's Avatar
    Join Date
    Apr 2003
    Posts
    8,892
    use that program to strip the comments out of it's own source...
    How cruel!

    So you explain the why of each line? That's different from most things I've seen so far.
    All the buzzt!
    CornedBee

    "There is not now, nor has there ever been, nor will there ever be, any programming language in which it is the least bit difficult to write bad code."
    - Flon's Law

  9. #9
    chococoder
    Join Date
    Nov 2004
    Posts
    515
    commenting ever line is bad practice.
    Sooner rather than later it leads to disparaties between comments and code and the next time someone has to maintain it there'll be floating questionmarks everywhere.

    Rather you should write your code to not need such elaborate comments, to effectively comment itself.

    Rather comment blocks of code the function of which isn't readily apparent, and document method and class headers by giving a functional description.
    Do the latter in the headerfiles.

  10. #10
    Registered User major_small's Avatar
    Join Date
    May 2003
    Posts
    2,787
    Quote Originally Posted by CornedBee
    How cruel!

    So you explain the why of each line? That's different from most things I've seen so far.
    that depends on what it is... I don't really have much of a formula for how I comment each line (not a formal one at least), but I try to find a way, unless it's blatantly obvious.

    Quote Originally Posted by jwenting
    Sooner rather than later it leads to disparaties between comments and code and the next time someone has to maintain it there'll be floating questionmarks everywhere.
    umm, I fail to see how this would happen... and part of the reason is to make maintenance easier... if you have to maintain, you're going to have to go deeper than the header file. the comments on the header files will only tell you what it's supposed to do, but when you look at the definitions, you won't know why it's not doing that, you'll just know that it's not.

    with commenting every line, you can see the intended logic as opposed to the written logic.
    Join is in our Unofficial Cprog IRC channel
    Server: irc.phoenixradio.org
    Channel: #Tech


    Team Cprog Folding@Home: Team #43476
    Download it Here
    Detailed Stats Here
    More Detailed Stats
    52 Members so far, are YOU a member?
    Current team score: 1223226 (ranked 374 of 45152)

    The CBoard team is doing better than 99.16% of the other teams
    Top 5 Members: Xterria(518175), pianorain(118517), Bennet(64957), JaWiB(55610), alphaoide(44374)

    Last Updated on: Wed, 30 Aug, 2006 @ 2:30 PM EDT

  11. #11
    Cat without Hat CornedBee's Avatar
    Join Date
    Apr 2003
    Posts
    8,892
    But not every single line of code forms a logical unit. Usually you have three or four lines perform a logical action. That's the way of imperative languages (in Haskell, I can indeed comment each line, because each line does a lot). And if you comment more than on each logical unit, you become redundant.
    All the buzzt!
    CornedBee

    "There is not now, nor has there ever been, nor will there ever be, any programming language in which it is the least bit difficult to write bad code."
    - Flon's Law

  12. #12
    Toaster Zach L.'s Avatar
    Join Date
    Aug 2001
    Posts
    2,686
    I very strongly agree with jwenting's point.

    My typical method is as follows. Comments on purpose, parameters, and output go at the function declaration; comments about a class go at the top of the appropriate header file; comments stating name of function, and a purpose field (which is usually left blank or has something very generic) go right before each function definition, more as a break in the code between functions; comments in code preceding code which would otherwise be difficult or hard to understand by someone who is at least fairly familiar with the system (i.e. rarely).

    Back to jwenting's point, a project I've worked on during my summers for the last few years is a rather large system (500k+ lines of C++ and Scheme). It has additionally undergone many changes over the past ten years. The consequence is, where people were extremely detailed in commenting everything, the details have often changed, and the comments have remained the same, and hence, they detract from the ability to understand what is going on because they are documenting long gone relics. I've been guilty of that a few times as well, but once realizing this problem, I switched to simply removing the comments, or updating them if time and patience permitted.

    So, if you have a single developer project and you have the discipline to update things as you modify them, then you can be as liberal you want with your comments. But keep in mind that if you have multiple developers who are working (or will be working) on the project, there is a fair chance that the above situation could occur.

    Cheers
    The word rap as it applies to music is the result of a peculiar phonological rule which has stripped the word of its initial voiceless velar stop.

  13. #13
    Registered User major_small's Avatar
    Join Date
    May 2003
    Posts
    2,787
    Quote Originally Posted by Zach L.
    So, if you have a single developer project and you have the discipline to update things as you modify them, then you can be as liberal you want with your comments. But keep in mind that if you have multiple developers who are working (or will be working) on the project, there is a fair chance that the above situation could occur.
    you don't seem to get my point though. removing comments is always faster and easier than writing new ones. therefore, writing them now and having to get rid of them later is better IMO than not writing them now and needing to figure them out later.

    usually the way I comment lines is not exactly what is going on, but explaining what's intended to happen. therefore, if you look at a line like this:
    Code:
    total-=tax;  //add the tax
    you can instantly tell that there's something wrong there. another example:
    Code:
    int x=(-B-sqrt(pow(B,2)-(4*A*C))/2*A); //positive value of quadratic formula
    the latter is a better example to my point.

    while developing, I usually read the comments and then strip them away so the code is more readable and you don't have the problem with comments not matching up with lines. another thing is, if you do need to go back and modify the code, as in the first two examples, what you fix will not make the comment wrong: it will actually make it right...
    Last edited by major_small; 12-10-2004 at 09:27 AM.
    Join is in our Unofficial Cprog IRC channel
    Server: irc.phoenixradio.org
    Channel: #Tech


    Team Cprog Folding@Home: Team #43476
    Download it Here
    Detailed Stats Here
    More Detailed Stats
    52 Members so far, are YOU a member?
    Current team score: 1223226 (ranked 374 of 45152)

    The CBoard team is doing better than 99.16% of the other teams
    Top 5 Members: Xterria(518175), pianorain(118517), Bennet(64957), JaWiB(55610), alphaoide(44374)

    Last Updated on: Wed, 30 Aug, 2006 @ 2:30 PM EDT

  14. #14
    Sweet
    Join Date
    Aug 2002
    Location
    Tucson, Arizona
    Posts
    1,801
    I have been getting better as of late. I ussually comment the header with what the class or struct is for, all the variables, functions, etc... Then throughout the cpp file comment some loops, if's and what not but most of my "green" is in the headers though
    Woop?

  15. #15
    Toaster Zach L.'s Avatar
    Join Date
    Aug 2001
    Posts
    2,686
    major_small, I understand your point, and in the cases you work with, I do not doubt that it works. You have the motivation and the discipline to make that system work, and you know exactly what the code should be doing and how. Therefore, the system works well for you.

    The example I was talking about was a bit more complicated. There were a fair number of programmers that worked or had worked on the system, and more importantly, it is not that the code did not work and needed to be debugged. The code worked fine at some point when the comments were written, and conformed to the comments. As the system evolved, however, a good bit of the underlying design changed, necessitating the particular code to take on new roles, give up some roles, or simply do things a bit differently. Comments in the code, however, were not always appropriately updated, so the comments simply documented a relic (which wasn't always clear unless you went through the code and understood it).

    If I understand what you are saying, then you have a multi-step process:
    - Write code and associated comments.
    - Debug code.
    - Remove comments.
    If this is the correct interpretation, then I agree with you that it is worthwhile, and I do it myself, but to a much lesser extent. Usually, I only apply this to large logical blocks of code, and then make sure to remove them before the code ever gets checked in (with the exception of those clearly documenting a specific, hard to follow piece of code as mentioned above -- but this is rare).

    And as a side note, the reason that comments often did not or do not get updated is not entirely that the programmer (myself included) is lazy, but rather, that there are more pressing issues at hand that require usable code to be written. If the project is for yourself, or not running on a (tight) deadline, then your method would be much more successful.

    My observations come from the software company I've worked for over the last several summers, where the conditions were pretty tight like that. I have since carried my habits over from there (partly because I personally don't find doing a lot of commenting fun).

    Anyway, those are my thoughts. I don't completely disagree with you, I just think that your method has a limited domain.

    Cheers
    Last edited by Zach L.; 12-10-2004 at 09:58 AM.
    The word rap as it applies to music is the result of a peculiar phonological rule which has stripped the word of its initial voiceless velar stop.

Page 1 of 2 12 LastLast
Popular pages Recent additions subscribe to a feed

Similar Threads

  1. WM_CAPTION causing CreateWindowEx() to fail.
    By Necrofear in forum Windows Programming
    Replies: 8
    Last Post: 04-06-2007, 08:23 AM
  2. Button handler
    By Nephiroth in forum Windows Programming
    Replies: 8
    Last Post: 03-12-2006, 05:23 AM
  3. Which style of if loops is most common?
    By dwks in forum A Brief History of Cprogramming.com
    Replies: 38
    Last Post: 08-25-2005, 03:18 PM
  4. WS_EX_COMPOSITED style (double buffering) problems
    By JasonD in forum Windows Programming
    Replies: 2
    Last Post: 10-12-2004, 11:21 AM
  5. Tab Controls - API
    By -KEN- in forum Windows Programming
    Replies: 7
    Last Post: 06-02-2002, 09:44 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21