Professional Commmenting Conventions

[N4g4rok]

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?

 

[DaveSimmons]

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.

 

[BrightCandle]

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.

 

[beginner99]

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.

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.

 

[Cogman]

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.

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

 

[N4g4rok]

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

What sort of documentation? Printed user guides and ERDs?

 

[mosco]

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.

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.

 

[DaveSimmons]

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

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.

 

[JamesV]

If you need a comment you need to rewrite the code.

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.

 

[N4g4rok]

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.

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?

 

[cytg111]

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.

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

 

[Cogman]

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.

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

 

[EagleKeeper]

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.

 

[clamum]

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.

 

[esun]

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.

 

[Aikouka]

If you need a comment you need to rewrite the code.

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.

 

[Apathetic]

Don't just write comments about what you're doing, but rather why you're doing it.

Dave

 

[brandonb]

Don't just write comments about what you're doing, but rather why you're doing it.

Dave

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)

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

 

[Munashiimaru]

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.