Thread: The Art of Writing Comments :: Software Engineering

  1. #1
    Registered User
    Join Date
    Nov 2001
    Posts
    1,348

    The Art of Writing Comments :: Software Engineering

    Hi.

    I am a C++ programmer with experience with MFC and Winsock. I am working on project that utilize MFC, Winsock, and more advanced C++ like that found in Modern C++ Design. I have a question about writing commends.

    I hate writing comments! Before you go off and post about responses, please consider my reasons. I understand the importance of comments from in terms of team project. In a team project where hundred and even thousands of programmers study and modify each other's code, comments are imperative. Comments are essential even in individual projects. Experienced programmers understand that we will one day read code we worked on six months ago. The bottomline is that comments are imperative to software implementation especially with C++ where some section of a code can be abstract and different to decipher.

    Nonetheless, comments are tedious! For example, let say you spend an hour on an algorithm. Now, you have to spend another ten, twenty, even thirty minutes commenting the class or a collection of classes. In the end, you have less time solving other problems.

    I want to know how do you programmers deal with commends in real-world team projects. Real-world projects vary from a simple simulation for NASA to an operating system. I know I am developing a bad habit that will hurt me in the end, but sometimes I get so caught up in solving problems that I ignore the comments. I remember all my code. Somethings I take a few minutes to see what goes on, but I always recommend it. Again, I understand the reason is because I am the person who wrote it.

    Lastly, is there an art to writing good comments? How do you know where, when, and what to write such that the comment is elegant and takes up little time and effort because it becomes natural?

    Thanks,
    Kuphryn

  2. #2
    booyakasha
    Join Date
    Nov 2002
    Posts
    208
    I usually write comments before or during writing the rest, of the code; I don't think it should be something you really have to go back and do after you are done with the coding.

  3. #3
    Guest Sebastiani's Avatar
    Join Date
    Aug 2001
    Location
    Waterloo, Texas
    Posts
    5,708
    I usually type short, one-line comments immediately after any confusing or contextually-dependant snippet. When I'm done I try to add more detailed comments, but usually not unless someone whines. (I hate writing comments, too). Mostly though, the best comment is a well named variable, in my opinion. Here are some annoyances of mine though:

    The Comment Freak:

    char * szBuff = new char [256]; /* allocate memory */ <--duh!
    for(;*szData; szData++) /* loop thru data */ <-- um, gotchya.

    ...etc.

    The Obscure Commentor:

    //...if missalign then do align...
    val = ( !((val >> 0x30) & ret) ) ? pz >> val : val >> pz;

    The Hungarian Gone Mad:

    PCHAR_T pchr_tMixData;
    PMX_SIZE pmx_szPmixSize=sizeof(tagPMX_STRUCT_TABLE_DATA);
    Code:
    #include <cmath>
    #include <complex>
    bool euler_flip(bool value)
    {
        return std::pow
        (
            std::complex<float>(std::exp(1.0)), 
            std::complex<float>(0, 1) 
            * std::complex<float>(std::atan(1.0)
            *(1 << (value + 2)))
        ).real() < 0;
    }

  4. #4
    Registered User
    Join Date
    Apr 2002
    Posts
    81
    The comments I write are a MUST.... if they're not there, I'm at a loss... as a beginner, I wish more people would have comments to their code.... I would absolutely learn quicker!!

    I hated writing them at first, but now I have to write them..... out of pure habit... I have to tell you.... it is the best "habit" I've ever picked up....

    I just type it after I type the command... I guess because I'm a beginner I think in pseudocode....

    if (this) // then this has to happen


    For the few seconds it takes me to type those few words... it saves me a world of headaches.....

    And that's from MyBeginner's Point of view
    "Our greatest glory consists not in never failing,
    but in rising every time we fall."

    Oliver Goldsmith (1730-1774).
    Anglo-Irish writer, poet and playwright.

  5. #5
    Guest Sebastiani's Avatar
    Join Date
    Aug 2001
    Location
    Waterloo, Texas
    Posts
    5,708
    "Comment Freak" are we, hmm?
    Code:
    #include <cmath>
    #include <complex>
    bool euler_flip(bool value)
    {
        return std::pow
        (
            std::complex<float>(std::exp(1.0)), 
            std::complex<float>(0, 1) 
            * std::complex<float>(std::atan(1.0)
            *(1 << (value + 2)))
        ).real() < 0;
    }

  6. #6
    Registered User
    Join Date
    Apr 2002
    Posts
    81
    Grades tell most of us we have to be.....

    Is it a bad thing? (to a degree....)
    "Our greatest glory consists not in never failing,
    but in rising every time we fall."

    Oliver Goldsmith (1730-1774).
    Anglo-Irish writer, poet and playwright.

  7. #7
    Guest Sebastiani's Avatar
    Join Date
    Aug 2001
    Location
    Waterloo, Texas
    Posts
    5,708
    Commenting is good. Just don't comment the blatently obvious. But above all, conform to your teachers expectations on assignments.
    Code:
    #include <cmath>
    #include <complex>
    bool euler_flip(bool value)
    {
        return std::pow
        (
            std::complex<float>(std::exp(1.0)), 
            std::complex<float>(0, 1) 
            * std::complex<float>(std::atan(1.0)
            *(1 << (value + 2)))
        ).real() < 0;
    }

  8. #8
    Registered User
    Join Date
    Apr 2002
    Posts
    81
    Just as I'd conform to my employer....

    Thanks for your comments!!!! Every little bit helps.....
    "Our greatest glory consists not in never failing,
    but in rising every time we fall."

    Oliver Goldsmith (1730-1774).
    Anglo-Irish writer, poet and playwright.

  9. #9
    ....
    Join Date
    Aug 2001
    Location
    Groningen (NL)
    Posts
    2,380
    Nonetheless, comments are tedious! For example, let say you spend an hour on an algorithm. Now, you have to spend another ten, twenty, even thirty minutes commenting the class or a collection of classes. In the end, you have less time solving other problems.
    In practice there is always less time to solve problems. But if you're organisation has a good software development process going on, then it is a lot easier for an engineer to deal with time. In my opinion comments should explain why something happens in the code, not what is actually happening. This is because the question what is going on in the code is a design issue which should be described in a design document. Someone who reads you're code should have read the design documents, so he/she knows what the code does. This reduces the number of comments in the code to only explaining why something in the code is done, for example a trick to implement some algorithm a bit more efficient or something which doesn't look very obvious.

    Commenting the class or a collection of classes or functions is something which is not necessary if you write a design document before coding. I always try to write a detailed design document, which saves a lot of time on coding and leads to very little commenting.

  10. #10
    Registered User
    Join Date
    Apr 2002
    Posts
    81
    Now I'm being pulled appart!!!!!

    Is it important to write comments or not?????

    They help me out in my own code!!! I'm told it's good practice..... should I spend my time typing comments or not???

    Books says yes.....
    "Our greatest glory consists not in never failing,
    but in rising every time we fall."

    Oliver Goldsmith (1730-1774).
    Anglo-Irish writer, poet and playwright.

  11. #11
    ....
    Join Date
    Aug 2001
    Location
    Groningen (NL)
    Posts
    2,380
    >Is it important to write comments or not?????

    Yes, but more important is how to comment.

    1. If you don't create a document in which you describe your design, then you will need a lot of comments to explain the code. If you do create a design document, less commenting is required.

    2. When reading the code, it should become clear what the code does. Only when things are not obvious at specific places, explain why you did something at those specific places.

    >They help me out in my own code!!!

    Then I'd recommend to practice the following to a small assignment: first write a design document in which you describe what the software must do and how it will do this, this is designing. Based upon your design(s), you start coding, but without commenting. At the end compare your code and your design(s). At the places where it isn't clear why things happen, you can put an explanation. When you do such, you'll learn when commenting is necessary. This gives you much more insight in the purpose of commenting then just put comments everywhere.

    In practice there are a lot of documents, depending on the size of the project ofcourse, written before coding happens.

    >Books says yes.....

    A book is theory, I've learned that theory is not always practice. :-)

  12. #12
    Blank
    Join Date
    Aug 2001
    Posts
    1,034
    I would try to use a documentation system like javadoc.

  13. #13
    ....
    Join Date
    Aug 2001
    Location
    Groningen (NL)
    Posts
    2,380
    Documentation systems are usefull to get, for example, an overview of classes and their members or an overview of the functions in a system. It can also be usefull to ensure that all documents in a project have the same layout, which makes reading documents easier.

    But they require that source-files contain a lot of comments. The documentation system extracts these comments, which are marked in the source by a special tag, from the source-files. In my opinion it often makes the code less readable.

    Also, if your design is detailed enough, there is no real need for such. In my work when designing, I also create an interface sheet, which describes in detail the class, in case an object oriented language is used. When using for example C, then it contains a description of the functions which form the interfaces.

    But I guess that most people, just like myself, don't use such formal methods when doing home-projects. Then documentations are especially usefull, especially since in home-projects the fun is more important than writing large documents.

  14. #14
    Code Goddess Prelude's Avatar
    Join Date
    Sep 2001
    Posts
    9,897
    >I want to know how do you programmers deal with commends in real-world team projects.
    I tend not to comment a great deal outside of file and function descriptions. The reason is because I try to keep my code clear enough so that comments aren't needed. If there is a section of code that isn't painfully obvious then I'll place a short comment describing the intention of that section so that readers don't get confused.

    >Lastly, is there an art to writing good comments?
    Most definitely.

    >How do you know where, when, and what to write such that the comment is elegant and takes up little time and effort because it becomes natural?
    Write self documenting code and when you are forced to write something that isn't immediately obvious, comment it.

    The two worst things you can do are comment badly (inaccurate, describe something obvious) and not comment at all. I find nothing more annoying than reading a non-trivial program (over 500 lines) with no comments. It's almost an insult, as if the author was saying "Go ahead, try and figure this out!". These programs are usually the ones that feel clarity is overrated.

    -Prelude
    My best code is written with the delete key.

  15. #15
    Senior Member joshdick's Avatar
    Join Date
    Nov 2002
    Location
    Phildelphia, PA
    Posts
    1,146
    If you're like me and aren't terribly thrilled about writing comments then I suggest writing code that doesn't need them as much. My programming teacher says that comments are somewhat needed but shouldn't be too necessary to understand a program. Descriptive identifiers are worth their weight in gold. I really wish programmers would realize that the way they choose to abbreviate an identifier is not necessarily easy to understand. That's why I think comments are best for identifiers. It is imperitive that other programmers can understand function names and variables.

    What someone said about writing a seperate document outlining what you're doing is a great idea. After that, only a sentence or two at the beginning of a program is needed to explain what it's doing.

    Besides from the previously mentioned reasons, the only other place comments are needed is where code isn't easily understandable. Most of the student programmers I learn with seem to think that all of their code is so obvious to them that it doesn't need comments. So often they are dead wrong. All programmers need to know that although they may be able to understand their code, not everyone else may. For that important reason, comments are a necessary evil.


    Sorry for the long rant there. I just started typing and didn't stop for a while.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Software Engineering
    By Cii in forum A Brief History of Cprogramming.com
    Replies: 21
    Last Post: 06-11-2004, 04:00 PM
  2. Lessons in writing good software - part 1
    By Salem in forum A Brief History of Cprogramming.com
    Replies: 17
    Last Post: 10-13-2003, 09:59 PM
  3. Piece of (software) art!
    By Carlos in forum Tech Board
    Replies: 2
    Last Post: 01-31-2003, 06:44 AM
  4. Best Engineering Developer (Circuits) Software
    By kuphryn in forum A Brief History of Cprogramming.com
    Replies: 4
    Last Post: 01-18-2003, 10:59 AM