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.

[sarcasm]
Well designed programs and well writen code don't need comments
[/sarcasm]

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.

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

I see, but what harm does it do?

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 ;) ).

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.

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.

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.

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

Quote:

---

lightatdawn wrote:
I comment everything

---

You mean something like this?

Code:

---

a++; /* Increment a by one. */

---

:D

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.

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.

>>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.

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