Professional Commmenting Conventions

Discussion in 'Programming' started by N4g4rok, Dec 28, 2012.

  1. N4g4rok

    N4g4rok Senior member

    Joined:
    Sep 21, 2011
    Messages:
    285
    Likes Received:
    0
    So, i'm beginning work as a professional programmer in the summer. I've taken a look at a lot of the code i've been writing and i can't decide if the way i'm commenting things is appropriate for professional code.

    What sort of comments do programmers and managers of programmers usually like to see?
     
  2. DaveSimmons

    DaveSimmons Elite Member

    Joined:
    Aug 12, 2001
    Messages:
    38,754
    Likes Received:
    33
    Once you're at your job, ask them for examples of what they consider good and bad commenting.

    At my job the rule I follow is to comment the clever parts and the unexpected parts, and anything else you might need explained when coming back to the code a year or two later. That's in addition to the comments of what a function does or a class variable is for of course.

    We have applications still being developed and maintained that have code dating back to 1999. Some parts of the code might not be updated for several years at a time, until some obscure bug is triggered or when we need to update the behavior. Looking back at something you did 2 years ago is about the same as updating code written by someone else.

    The other rule I follow is to try to keep the code clean and simple so it doesn't need comments. A tricky for-loop construct that moves all of the code into the for (x; y; z) part might be impressive but you'll be annoyed 2 years later when you need to unravel it. Unless you're optimizing some bottleneck, don't try to show off.
     
    #2 DaveSimmons, Dec 28, 2012
    Last edited: Dec 28, 2012
  3. BrightCandle

    BrightCandle Diamond Member

    Joined:
    Mar 15, 2007
    Messages:
    4,763
    Likes Received:
    0
    If you need a comment you need to rewrite the code. Comments should be avoided as much as possible. Rather than doing the hack and placing a warning comment just do better.

    Documentation on the other hand is valuable and well worth doing when its needed.
     
  4. beginner99

    beginner99 Platinum Member

    Joined:
    Jun 2, 2009
    Messages:
    2,832
    Likes Received:
    4
    I agree. However when it is needed I add comments why something is done that does not seem very "intuitive" or "logical". While that should also be in documentation outside of code IMHO it makes sense to have it in code as well. Can save a lot of time.
     
  5. Cogman

    Cogman Lifer

    Joined:
    Sep 19, 2000
    Messages:
    10,086
    Likes Received:
    14
    I generally comment of WTF pieces of code. I try my hardest not to write them, but, you know, sometimes you can't do anything about where you are working or the API you are working with. (90% of the time I write WTF code, it is because the framework does pulls a WTF on me).
     
  6. N4g4rok

    N4g4rok Senior member

    Joined:
    Sep 21, 2011
    Messages:
    285
    Likes Received:
    0
    What sort of documentation? Printed user guides and ERDs?
     
  7. mosco

    mosco Senior member

    Joined:
    Sep 24, 2002
    Messages:
    940
    Likes Received:
    1
    While noble, I don't think thats very practical advice. As a full time iOS develop supporting iOS 4.3, 5, 6 and also now working on the same android app supporting all the way back to 2.2, there are a lot of places where creating little hacks is about as good as you are going to do, and I make sure to comment the hell out of all them.
     
  8. DaveSimmons

    DaveSimmons Elite Member

    Joined:
    Aug 12, 2001
    Messages:
    38,754
    Likes Received:
    33
    That's a good example. Sometimes the API or SDK documentation is unclear or flat-out wrong, and a comment can explain how you're getting it to work.

    I'll stick in a Microsoft KB ID or CodeProject article title for something tricky since context help on the API call would not be enough to someone who hadn't just found the correct information.

    Unless you want to maintain and sync a 1,000 page developer notes doc that covers every function, right there in the code is the best place to put that info. IMHO of course.
     
  9. JamesV

    JamesV Platinum Member

    Joined:
    Jul 9, 2011
    Messages:
    2,002
    Likes Received:
    1
    Dumbest thing I've read here in a while, unless you are just commenting on code you write, that you and you alone will ever have to look at.

    If you've ever had to work on large programs someone else wrote, then you know what I mean. I spent months fixing an in-house software package with zero comments. Sure I could figure out what he was doing, but the same work could have taken weeks instead of months if I didn't have go over it line by line. Didn't help the first guy copy/pasted much of the code out of a programming book (found over 300 unused global variables believe it or not), but still.

    Comments are stripped out when compiling, so there is no reason not to use them, unless you are planning on seriously pissing someone off in the future that has to look at what you have done. Most businesses have standards, and if they don't, just comment in plain English for those that might come after you... they will appreciate it.
     
  10. N4g4rok

    N4g4rok Senior member

    Joined:
    Sep 21, 2011
    Messages:
    285
    Likes Received:
    0
    The company i will be working for will be too large to go hunt down someone responsible for a nasty bug, so feel like in-line comments will have their place.

    Where, if it exists, is the line drawn for over commenting? Is it something that should be worried about in a large environment?
     
  11. cytg111

    cytg111 Platinum Member

    Joined:
    Mar 17, 2008
    Messages:
    2,241
    Likes Received:
    14
    Thank you. The real world is hardly very often "ideal" or "noble", and sometimes you're required to solve some hairy ass complex shit given some very less than ideal circumstances.
    I like that comment that says

    //
    // Dear maintainer:
    //
    // Once you are done trying to 'optimize' this routine,
    // and have realized what a terrible mistake that was,
    // please increment the following counter as a warning
    // to the next guy:
    //
    // total_hours_wasted_here = 42
    //
     
  12. Cogman

    Cogman Lifer

    Joined:
    Sep 19, 2000
    Messages:
    10,086
    Likes Received:
    14
    Too many comments are just as bad (if not worse) than too few comments. I find properly named variables and methods to be far more useful than loads of comments.

    No amount of comments would have made the code you worked with easier to understand. The type of programmer that would just insert unused global variables is the same type of programmer that would write comments like "Setting X to 42".

    BrightCandle's advice is decent, time and resources permitting. Otherwise, the question should be asked "What would someone else think if they came across this code and how could I make it easier for them?".

    Where comments go bad is when they fall out of sync with the code (which happens more often than you might think). At that point, you train future developers to just ignore the comments (in which case they start to decrease readability).
     
  13. EagleKeeper

    EagleKeeper Discussion Club Moderator<br>Elite Member
    Staff Member

    Joined:
    Oct 30, 2000
    Messages:
    42,600
    Likes Received:
    0
    The more a module can be self documenting, the less comments needed.

    However, no matter the name of the module, if it has parameters, the module should be documented.

    And if the module name does not clearly describe what is being done, document.

    I have worked multiple projects where the module name is clear as mud. The "standards"
    require names built by project, system and subsystem. In that case a good three to four line description is useful.

    Comments are not for you, it is for the poor slob that had to figure out how much of a smart ass you were two years down the road.

    Work in an assembly project and the value of comments becomes self evident.

    If there is a questions on what an area if code is for or how it works, document it.

    Boiler plate headers are great for building documentation required by specs or a customer. Many government related projects will require quality documentation that commercial systems ignore.
     
  14. clamum

    clamum Lifer

    Joined:
    Feb 13, 2003
    Messages:
    23,702
    Likes Received:
    6
    Dave's first post is great advice IMO.

    At my current job, I honestly don't do much commenting at all because the code is quite straight-forward, and variables and methods are named appropriately, and all methods and class variables have XML comments (I'm using .NET) describing what should be happening. But if I have to write some tricky code, absolutely will I add some clarification.
     
  15. esun

    esun Platinum Member

    Joined:
    Nov 12, 2001
    Messages:
    2,214
    Likes Received:
    0
    The company you go work at will likely have some style guidelines as to how and when you should comment. I generally try to comment on why I'm doing something, or what the expected behavior is, or any assumptions that I'm making when doing something (if I don't assert those assumptions for some reason).

    I find it useful to actually refer or link to relevant documentation when appropriate (e.g., // This handles the special case where XYZ, see BUG1234), again, so people can look up relevant information on why things are done a certain way.

    The thing you generally want to avoid is duplicated work. When I'm working on a bug, for example, I keep running notes in the bug comments so that if I don't solve the bug, the next guy coming along can read those notes and start from where I left off. Likewise, my code should allow someone to come in and understand what's going on without having to read every line of it. Even if the code is "self-documenting", it's best to summarize the important stuff somewhere so the next person can avoid reading the whole damn thing to get the idea.
     
  16. Aikouka

    Aikouka Lifer

    Joined:
    Nov 27, 2001
    Messages:
    27,091
    Likes Received:
    5
    Honestly, I just cannot agree with this. Sure, if you're doing some crazy things just to try and write less code, which may actually end up requiring more processing time, then you may want to rewrite it. However, there are plenty of cases where I had to do something a specific way that was simply complex enough. If I end up doing something like that, I have no qualms with writing a long comment to explain why I did it that way.
     
  17. Apathetic

    Apathetic Platinum Member

    Joined:
    Dec 23, 2002
    Messages:
    2,572
    Likes Received:
    0
    Don't just write comments about what you're doing, but rather why you're doing it.

    Dave
     
  18. brandonb

    brandonb Diamond Member

    Joined:
    Oct 17, 2006
    Messages:
    3,731
    Likes Received:
    1
    I typically follow this method. Typically in the business world you can look at things in 2 ways.

    Business requirements.
    Technical reasons why I'm doing something.

    I comment to list both.

    For example the below. There is a technical reason to save off a copy of an object (because its a key in a dictionary collection) so when I fiddle with it (and in my case save the object to the db), I break the ability to find it in the dictionary, so I made a comment.

    But as you can tell from my variable names, the ORIG is the updated one, not the original. So it was flip-flopped in my variable naming. So its slightly confusing (i'll fix that some day).

    (Excuse my VB.net)

    Code:
    
                ' ----------------------------------------------------------------------------------
                ' Save Notes (if not already saved)
                ' ----------------------------------------------------------------------------------
                If objr_DISPOSITION.objm_LOGNOTE IsNot Nothing Then
    
                    For intl_X = 0 To objr_DISPOSITION.objm_LOGNOTE.Count - 1
    
                        Dim objl_LOGNOTE As ORM.DB.clsLogNote = objr_DISPOSITION.objm_LOGNOTE(intl_X)
    
                        If objl_LOGNOTE.IdLogNote Is Nothing AndAlso objl_LOGNOTE.Inactive = True Then
                            Continue For
                        End If
    
                        ' Copy into lognote original so we can save it, but also leave the original intact so we can use it in collection searching.
                        Dim objl_LOGNOTEORIG As New ORM.DB.clsLogNote
                        objl_LOGNOTEORIG.Copy(objl_LOGNOTE)
    
                        If Not objr_CACHE.SaveLogNote(objr_CONN, objl_LOGNOTEORIG) Then
                            Return False
                        End If
    
                        objr_DISPOSITION.objm_LOGNOTE.Item(objr_DISPOSITION.objm_LOGNOTE.IndexOf(objr_DISPOSITION.objm_LOGNOTE(intl_X))) = objl_LOGNOTEORIG
    
                        Dim objl_MAP As ORM.DB.clsMapLogNoteDisposition
                        objl_MAP = objr_CACHE.MapLogNoteDispositions_UidDefWorkflowType_IdDisposition_IdLogNote(objr_CONN, intv_UIDDEFWORKFLOWTYPE, objr_DISPOSITION.objm_DBENTRY.IdDisposition, objl_LOGNOTEORIG.IdLogNote)
    
                        If objl_MAP Is Nothing Then
                            objl_MAP = New ORM.DB.clsMapLogNoteDisposition
                            objl_MAP.Sys = False
                            objl_MAP.Inactive = False
                            objl_MAP.UidDefWorkflowType = intv_UIDDEFWORKFLOWTYPE
                            objl_MAP.IdLogNote = objl_LOGNOTEORIG.IdLogNote
                            objl_MAP.IdDisposition = objr_DISPOSITION.objm_DBENTRY.IdDisposition
                        Else
                            objl_MAP.Inactive = objl_LOGNOTEORIG.Inactive
                        End If
    
                        If Not objr_CACHE.SaveMapLogNoteDisposition(objr_CONN, objl_MAP) Then
                            Return False
                        End If
    
                        If objr_DISPOSITION.objm_LOGNOTE_ATTACHMENTS.ContainsKey(objl_LOGNOTE) Then
                            For Each objl_MAP2 As ORM.DB.clsMapLogNoteAttachment In objr_DISPOSITION.objm_LOGNOTE_ATTACHMENTS(objl_LOGNOTE)
                                objl_MAP2.IdLogNote = objl_LOGNOTEORIG.IdLogNote
                                objr_CACHE.SaveMapLogNoteAttachment(objr_CONN, objl_MAP2)
                            Next
                        End If
    
                    Next
    
                End If
    
    
     
  19. Munashiimaru

    Munashiimaru Junior Member

    Joined:
    Jan 14, 2013
    Messages:
    23
    Likes Received:
    0
    Most of my comments are for the automated documenting stuff. I comment all class, almost all functions, and usually global variables that way when people are reading other parts of my code they can just mouse over to get a description of it.

    I comment code that isn't straight forward from the keywords/variable names. I also never abbreiviate unless it's a business term, put some thought into my variable names, and use small functions so it's pretty rare my code isn't straight forward. Last time I wrote comments in the middle of a function, it was because the database/use case was designed goofy, and I had to use extra logic to get the right functionality on my page without changing the database/gutting some code that was written by someone else.
     
Loading...