Code comments

This is a discussion on Code comments within the A Brief History of Cprogramming.com forums, part of the Community Boards category; I just got a job using Delphi & Dataflex, with some VB CE coming up (big whoop, I know). Would ...

  1. #1
    Registered User
    Join Date
    Jan 2002
    Posts
    559

    Code comments

    I just got a job using Delphi & Dataflex, with some VB CE coming up (big whoop, I know). Would help if I knew either one, but...
    Anyway, as the new guy, I'm mostly doing maintenance & bug fixes. The programs are fairly long and composed of several exe's. Thousands of lines of code. There is very little commenting of the code, and some of that isn't much more than repeating the code itself.
    It would be very useful if more germane comments were added. Just a line or two stating what the function is supposed to accomplish would be nice. I can see that x is being assigned to y, e.g, but those values may come from or be passed back to an entirely different module.
    Maybe Prelude or other programmers with on the job experience could write about this more knowledgably. But right now I can spend hours just trying to trace what happens and why with a couple line code change.
    Truth is a malleable commodity - Dick Cheney

  2. #2
    Registered User
    Join Date
    Feb 2002
    Posts
    591
    [sarcasm]
    Well designed programs and well writen code don't need comments
    [/sarcasm]

  3. #3
    Microsoft. Who? MethodMan's Avatar
    Join Date
    Mar 2002
    Posts
    1,198
    Well for projects that we had to do, 25% of the mark went to good commeting. So It is a very important aspect of programming, since 1/4 is weighted on the project.
    -MethodMan-

    Your Move:Life is a game, Play it; Life is a challenge, Meet it; Life is an opportunity, capture it.

    Homepage: http://www.freewebs.com/andy_moog/home.html

  4. #4
    Code Goddess Prelude's Avatar
    Join Date
    Sep 2001
    Posts
    9,796
    Comments are critical to the maintenance of a program. They should be up to date, informative, and general enough to survive an update in the code. Most importantly, and this is the part that most of my project team doesn't understand, don't comment code that screams out what it does. For example:
    Code:
    /*Check if a is valid and see why if it isn't*/
    if (err & VALID){
        a_handler (&a);
    }
    else{
        determine_error (&err);
    }
    This is more or less what someone I work with wrote. The problem is that the comment is worthless, the code spells it out on its own. A good rule of thumb for commenting is to comment anything that seems even the slightest bit obscure, has potential for errors in an update, or uses a less than common construct for no apparent reason. When you do comment, make sure that you specify the meaning behind the code and not the mechanics of it. Any programmer worth their paycheck will be able to figure out the mechanics, but most times the reason behind the mechanics is what is confusing. For the most part I'll comment sparsely because my coding style is simplistic enough for even the greenest of maintainers to figure out, but I still make sure that anyone who reads it will have an idea of what is going on.

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

  5. #5
    Registered User
    Join Date
    Jan 2002
    Posts
    559
    I see, but what harm does it do?
    Truth is a malleable commodity - Dick Cheney

  6. #6
    Peace
    Join Date
    Aug 2001
    Posts
    1,510
    I'm on the comment bandwagon. I comment everything. Running C-Metrics on my latest project I discover the following stats.

    Over 83 files with 415 functions, 31 classes, 16 structs:

    34126 Lines Total
    20732 Effective
    5126 Comment
    4677 Blank

    So as you can see I'm not afraid to drop some space and a few lines of comments to make my code more readable. I swear by it. Next to proper indentation and logical variable/function naming, I think that commenting is one of the most important things you can do. Mind you, I have basically no out-of-project documentation so my comments do double duty.

    >>/*Check if a is valid and see why if it isn't*/

    In this case I think I would have actually placed a comment but nothing like that one. I likely would likely leave some info about what we may be looking for and what will happen if we do get and error. It would really depend on the circumstance though. If, for instance, that code was checking for a valid data segment in my linked list I would want to have a comment about what will happen to my list traversal should an error be found. Will the app be exiting? Will anything need patching up? Will things go on as planned after my error handler fixes the problem?

    I try to keep my comments very brief and to the point (unlike my post ).
    "There's always another way"
    -lightatdawn (lightatdawn.cprogramming.com)

  7. #7
    Just because ygfperson's Avatar
    Join Date
    Jan 2002
    Posts
    2,493
    i gotta work on commenting. when i write stuff (if it ever gets finished), i hardly ever comment, except to comment out lines of code in debugging. i've never had anyone maintain my programs, not even me, so i don't bother with it much. most of the time, when i look at my older programs, i see so many things i did wrong i decide just to rewrite the program again. i can see its uses in a team enviroment, though.

  8. #8
    Still A Registered User DISGUISED's Avatar
    Join Date
    Aug 2001
    Posts
    499
    The company I am working for in the work study program I am in requires that we give pre and post conditions of all functions regardless of their simplicity. Sometimes it seems a little redundant but other times very helpful. In school if we don't comment our code it's an automatic F. That will remind you everytime, if not you'll only forget once.

  9. #9
    I'm Back
    Join Date
    Dec 2001
    Posts
    556
    From personal experience I can say that code comments are very important.

    I rarely ever used to comment my programs but after i re-started one of my unfinished programs, I got so muddled up that I think it is must.

  10. #10
    Registered User
    Join Date
    Jul 2002
    Posts
    25

    VB

    I wrote a program that scanned my vb code. For a project I'm working on at the moment;

    1 Form
    1 Class Module
    6 Code Modules
    82 Procedures
    34 Functions
    25 Properties
    114 API Declarations
    668 Variables Declared
    263 Constants
    29 User Definted Types
    20 Enumerators
    153 If Statements
    13 Select Case Statements
    20 For loops
    5 Do..While Loops
    1034 Blank Lines
    1440 Comment Lines (not inc. tagged comments at end of line)
    1869 Code Lines

    Total Lines: 5614
    DiskJunky

  11. #11
    Registered User raimo's Avatar
    Join Date
    Jun 2002
    Posts
    107
    lightatdawn wrote:
    I comment everything
    You mean something like this?
    Code:
    a++; /* Increment a by one. */


    I think only the actual idea should be commented. Some strange things like /*Divide a by 2 and check if it's zero*/ is completely useless. Reading the code through is much more efficient way to understand it if it's written by someone else.
    I am not using Dev-C++.
    #!/usr/bin/env python
    import sys;file=open(sys.argv[0]);print file.read();file.close()

  12. #12
    Mayor of Awesometown Govtcheez's Avatar
    Join Date
    Aug 2001
    Location
    MI
    Posts
    8,825
    Since I try to keep my functions short, I usually commetn at the beginning of a function (except main) and that's it. If the funciton's length starts getting out of hand or I do something weird in it, then I'll comment those specifically.

  13. #13
    Peace
    Join Date
    Aug 2001
    Posts
    1,510
    >>a++; /* Increment a by one. */

    Heh, ah... no. But the following instance would deserve a comment:

    Code:
    //Comment regarding the following
    Tag = AssignedTag;
    for(short inc = 0; inc < LIST_DAT_LEN; inc ++)
    {
       if (pList->ListDat[inc] == Tag)
          pList->ListTag = PreviousTag;
    }
    I mean, what it does is pretty obvious. Why it does it is another matter entirely. Obviously I just made that up so it has no real purpose, but one is likely to find something simular to it in actual applications. I dont comment to illustrate what the code is doing; Anyone reading my code had damn well better be able to understand the concepts. I comment to make clear why the code needs to do what it is doing and what the result it will have on the application.

    Its even possible that I would comment further regarding what the Tag var was being assigned from and why and also where the PreviousTag var was coming from and why we were reassigning it.
    "There's always another way"
    -lightatdawn (lightatdawn.cprogramming.com)

  14. #14
    Registered User
    Join Date
    Jul 2002
    Posts
    25

    Exactly

    Right. In vb I'd comment with something like;
    Code:
    Public Function GetAfter(ByVal strSearch As String, _
                             ByVal strMarker As String) _
                             As String
        'This will return all the text after the
        'first occurance of the specified string
        
        Dim lngMarkerPos As Long    'the position of the marker string withing the searching string
        Dim strRest As String       'holds everything after the marker string
        
        'find last occurance of the marker text
        lngMarkerPos = InStrRev(strSearch, strMarker)
        
        If lngMarkerPos > 0 Then
            'return all text after the marked position
            strRest = Right(strSearch, _
                            (Len(strSearch) - _
                             (lngMarkerPos + Len(strMarker) - 1) _
                             ) _
                            )
        Else
            'if the string was not found, then return all the
            'searching string
            GetAfter = strSearch
        End If
        
        GetAfter = strRest
    End Function
    
    Public Function GetFileName(ByVal strLine As String) _
                                As String
        'This will return all the text after the
        'first occurance of the specified string
        
        Dim strName As String
        
        'return everything after the backslash
        strName = Trim(GetAfter(strLine, "\"))
        
        'return the filename
        GetFileName = strName
    End Function
    maybe overkill, but I've found over the years that it make going back over code a hell of a lot easier
    DiskJunky

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Replies: 23
    Last Post: 04-20-2009, 08:35 AM
  2. Replies: 1
    Last Post: 03-21-2006, 07:52 AM
  3. Seems like correct code, but results are not right...
    By OmniMirror in forum C Programming
    Replies: 4
    Last Post: 02-13-2003, 01:33 PM
  4. Interface Question
    By smog890 in forum C Programming
    Replies: 11
    Last Post: 06-03-2002, 06:06 PM
  5. code and comments check
    By Unregistered in forum C Programming
    Replies: 1
    Last Post: 01-17-2002, 12:45 PM

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