Go Back   AnandTech Forums > Software > Programming

Forums
· Hardware and Technology
· CPUs and Overclocking
· Motherboards
· Video Cards and Graphics
· Memory and Storage
· Power Supplies
· Cases & Cooling
· SFF, Notebooks, Pre-Built/Barebones PCs
· Networking
· Peripherals
· General Hardware
· Highly Technical
· Computer Help
· Home Theater PCs
· Consumer Electronics
· Digital and Video Cameras
· Mobile Devices & Gadgets
· Audio/Video & Home Theater
· Software
· Software for Windows
· All Things Apple
· *nix Software
· Operating Systems
· Programming
· PC Gaming
· Console Gaming
· Distributed Computing
· Security
· Social
· Off Topic
· Politics and News
· Discussion Club
· Love and Relationships
· The Garage
· Health and Fitness
· Merchandise and Shopping
· For Sale/Trade
· Hot Deals with Free Stuff/Contests
· Black Friday 2013
· Forum Issues
· Technical Forum Issues
· Personal Forum Issues
· Suggestion Box
· Moderator Resources
· Moderator Discussions
   

Reply
 
Thread Tools
Old 12-28-2012, 10:13 PM   #1
N4g4rok
Senior Member
 
N4g4rok's Avatar
 
Join Date: Sep 2011
Location: Northwest Arkansas, USA
Posts: 284
Default Professional Commmenting Conventions

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?
__________________
Primary: Hades
> AMD Phenom II X4 970 @ 3.9 Ghz + Antec Kuhler 620
> ASUS M4A79XTD EVO
> XFX Radeon R7950 Black Edition
> 128GB Samsung 830 SSD + 2TB Hitachi Deskstar HDD
> 8GB G.SKILL Ripjaws DDR3 RAM @ 1600 Mhz
> NZXT Hades Case

Home Server: Charon
> AMD Sempron 145 @ 2.8 Ghz + Stock cooler
> GigaByte GA-M68MT-S2
> 2TB Seagate Barracuda Green HDD + 2TB Samsung Spinpoint HDD
> 4GB Crucial DDR3 RAM @ 1333
> NZXT Hush Case
N4g4rok is offline   Reply With Quote
Old 12-28-2012, 10:31 PM   #2
DaveSimmons
Elite Member
 
Join Date: Aug 2001
Location: Bellevue, WA
Posts: 37,046
Default

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.

Last edited by DaveSimmons; 12-28-2012 at 10:34 PM.
DaveSimmons is offline   Reply With Quote
Old 12-29-2012, 04:35 AM   #3
BrightCandle
Diamond Member
 
BrightCandle's Avatar
 
Join Date: Mar 2007
Posts: 4,360
Default

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.
__________________
i7 3930k @4.4, 2xMSI GTX 680, 16GB Corsair 2133 RAM, Crucial m4 500GB, Soundblaster Z
Custom watercooled by 2x MCR 320 and 1 MCR 480
Zowie Evo CL EC2, Corsair K70, Benq XL2411T
BrightCandle is offline   Reply With Quote
Old 12-29-2012, 07:12 AM   #4
beginner99
Platinum Member
 
Join Date: Jun 2009
Posts: 2,121
Default

Quote:
Originally Posted by BrightCandle View Post
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.
beginner99 is offline   Reply With Quote
Old 12-29-2012, 07:35 AM   #5
Cogman
Diamond Member
 
Cogman's Avatar
 
Join Date: Sep 2000
Location: A nomadic herd of wild fainting goats
Posts: 9,740
Default

Quote:
Originally Posted by beginner99 View Post
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).
__________________
CogBlog - Random Babblings of Cogman mainly focused on software.
Cogman is offline   Reply With Quote
Old 12-29-2012, 11:09 AM   #6
N4g4rok
Senior Member
 
N4g4rok's Avatar
 
Join Date: Sep 2011
Location: Northwest Arkansas, USA
Posts: 284
Default

Quote:
Originally Posted by BrightCandle View Post
Documentation on the other hand is valuable and well worth doing when its needed.
What sort of documentation? Printed user guides and ERDs?
__________________
Primary: Hades
> AMD Phenom II X4 970 @ 3.9 Ghz + Antec Kuhler 620
> ASUS M4A79XTD EVO
> XFX Radeon R7950 Black Edition
> 128GB Samsung 830 SSD + 2TB Hitachi Deskstar HDD
> 8GB G.SKILL Ripjaws DDR3 RAM @ 1600 Mhz
> NZXT Hades Case

Home Server: Charon
> AMD Sempron 145 @ 2.8 Ghz + Stock cooler
> GigaByte GA-M68MT-S2
> 2TB Seagate Barracuda Green HDD + 2TB Samsung Spinpoint HDD
> 4GB Crucial DDR3 RAM @ 1333
> NZXT Hush Case
N4g4rok is offline   Reply With Quote
Old 12-29-2012, 12:27 PM   #7
mosco
Senior Member
 
Join Date: Sep 2002
Posts: 925
Default

Quote:
Originally Posted by BrightCandle View Post
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.
mosco is offline   Reply With Quote
Old 12-29-2012, 02:01 PM   #8
DaveSimmons
Elite Member
 
Join Date: Aug 2001
Location: Bellevue, WA
Posts: 37,046
Default

Quote:
Originally Posted by Cogman View Post
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.
DaveSimmons is offline   Reply With Quote
Old 12-29-2012, 09:50 PM   #9
JamesV
Golden Member
 
JamesV's Avatar
 
Join Date: Jul 2011
Location: Cleveland, OH
Posts: 1,706
Default

Quote:
Originally Posted by BrightCandle View Post
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.
JamesV is offline   Reply With Quote
Old 12-29-2012, 09:57 PM   #10
N4g4rok
Senior Member
 
N4g4rok's Avatar
 
Join Date: Sep 2011
Location: Northwest Arkansas, USA
Posts: 284
Default

Quote:
Originally Posted by JamesV View Post
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?
__________________
Primary: Hades
> AMD Phenom II X4 970 @ 3.9 Ghz + Antec Kuhler 620
> ASUS M4A79XTD EVO
> XFX Radeon R7950 Black Edition
> 128GB Samsung 830 SSD + 2TB Hitachi Deskstar HDD
> 8GB G.SKILL Ripjaws DDR3 RAM @ 1600 Mhz
> NZXT Hades Case

Home Server: Charon
> AMD Sempron 145 @ 2.8 Ghz + Stock cooler
> GigaByte GA-M68MT-S2
> 2TB Seagate Barracuda Green HDD + 2TB Samsung Spinpoint HDD
> 4GB Crucial DDR3 RAM @ 1333
> NZXT Hush Case
N4g4rok is offline   Reply With Quote
Old 12-30-2012, 02:51 PM   #11
cytg111
Golden Member
 
Join Date: Mar 2008
Posts: 1,279
Default

Quote:
Originally Posted by mosco View Post
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
//
__________________
404
cytg111 is offline   Reply With Quote
Old 12-30-2012, 05:53 PM   #12
Cogman
Diamond Member
 
Cogman's Avatar
 
Join Date: Sep 2000
Location: A nomadic herd of wild fainting goats
Posts: 9,740
Default

Quote:
Originally Posted by JamesV View Post
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).
__________________
CogBlog - Random Babblings of Cogman mainly focused on software.
Cogman is offline   Reply With Quote
Old 01-01-2013, 06:00 PM   #13
EagleKeeper
Discussion Club Moderator
Elite Member
 
EagleKeeper's Avatar
 
Join Date: Oct 2000
Location: Bumps west of Denver
Posts: 42,600
Default

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.
__________________
F15 Air Superiority Fighter - Never has one been lost in aerial combat (104 kills)
EagleKeeper is offline   Reply With Quote
Old 01-04-2013, 03:39 PM   #14
clamum
Lifer
 
clamum's Avatar
 
Join Date: Feb 2003
Posts: 21,481
Default

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.
__________________
\ Battlefield 4 Stats /\ Heat /
clamum is online now   Reply With Quote
Old 01-04-2013, 09:53 PM   #15
esun
Platinum Member
 
Join Date: Nov 2001
Posts: 2,214
Default

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.
__________________
My Heatware
esun is offline   Reply With Quote
Old 01-10-2013, 02:53 PM   #16
Aikouka
Lifer
 
Aikouka's Avatar
 
Join Date: Nov 2001
Location: Alabama
Posts: 24,305
Default

Quote:
Originally Posted by BrightCandle View Post
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.
Aikouka is online now   Reply With Quote
Old 01-14-2013, 02:43 PM   #17
Apathetic
Platinum Member
 
Join Date: Dec 2002
Location: Raleigh, NC
Posts: 2,518
Default

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

Dave
Apathetic is offline   Reply With Quote
Old 01-14-2013, 03:18 PM   #18
brandonb
Diamond Member
 
Join Date: Oct 2006
Posts: 3,343
Default

Quote:
Originally Posted by Apathetic View Post
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)

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
__________________
Computer Setup
Intel Ivy Bridge 3550, AsRock Z75 Pro3, 8 gig GSkill 1600 8-8-8-24 timing, Crucial m4 64gig, 500meg WD RE4, ATI 7970 3GB, LG IPS236V x 3, Windows 8, Antec Sonata Solo 2, Antec 550watt PS.
brandonb is offline   Reply With Quote
Old 01-15-2013, 07:59 AM   #19
Munashiimaru
Junior Member
 
Join Date: Jan 2013
Posts: 23
Default

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.
Munashiimaru is offline   Reply With Quote
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump


All times are GMT -5. The time now is 11:35 PM.


Powered by vBulletin® Version 3.8.7
Copyright ©2000 - 2014, vBulletin Solutions, Inc.