[Martyn.Rae]

Have you ever been frustrated seeing code like this:

	// This section of code does something ... it's way above my head but it seems to give
	// the end user what they want (btw - I wrote this code!)

	   ... code ...

	// Hope you enjoyed that - please send me a postcard if you have figured out what it
	// does :)

or another comment I have seen

	// Look mom ... no hands!!!

What is the point?

Do you comment functions before each class or function?
Do you comment sections of code?

Would you change the comments in a piece of code to reflect the changes you have just made?

Answers on a postcard to ...

This post has been edited by Martyn.Rae: 31 January 2010 - 02:56 PM

[Auzzie]

I generally comment before each function describing what it does, and using doctype tagging.... Throughout the code i will sometimes add a few comments of any possible bugs or problems or if i think i might have overcomplicated that section, just to stand it out.

[Raynes]

I comment individual functions to explain what they are there for, but primarily for myself.

In Clojure, all vars have metadata with a :doc key where you can put documentation for that specific var. You can call up that documentation later using (doc <insert var here>). Because of that, I tend to use plain old comments very rarely, and just stick to doc strings. I'll only use comments if I think a piece of code is hard to understand without explicitly explaining the code.

[Sergio Tapia]

Using C#, I always use XML Comments to give the method a summary of what it does, what I need to give it, and what it returns.

When using normal inline comments, I like to write down why I'm doing something this way, instead of writing what I'm doing.

The why is always more important than the what.

[Martyr2]

I comment functions to let others know the purpose, expected inputs and outputs and any additional info that may be relevant. I do not write comments that do not refer to my intentions or thoughts on the code. I use single line comments to also describe the flow without getting in the way of reading the flow of the code. This usually means I have 1 or 2 lines at the beginning of each function and probably about 1 comment line for every 5 - 10 lines of function code.

If you find yourself writing too many comments to get the point across, it means your code is too complex and needs to be decomposed further. If you have too little comments it means you are making a lot of assumptions about whoever will read it later and could make your code unmaintainable.

In short, use comments sparingly, but do use them.

[macosxnerd101]

As a High School student, I avoid using comments extensively (more than 1-2 single line comments per program) for a few reasons: one- I'm the only person working with my code, two- the programs only take 100-200 lines max, and three- they decrease my overall productivity (in other words, it takes me longer to write the program without comments than with). Now if I was coding in a professional or team environment, I would definitely use them as it would make my team mates' lives easer.

[erik.price]

I'm with macosxnerd with this one. Most of my comments will end up being reminders to myself to fix or implement things.

I do generally write some explanatory comments on the functions of methods and whatnot

[0xFF]

Here's the problem-- When I hire you, your not going to have any practice with meaningful comments.

[erik.price]

I'm 16, so I've still got a few years to practice.

And I do know how to effectively document a piece of code with comments (mostly), I just don't have a use for it that often

[0xFF]

Here's the problem--
Are you going to be that guy the managers make fun of behind his back because he sits there and spins his propeller hat all day writing code with geek stamped on your head, taking instructions from the guy designing processes, or are you going to train yourself to be something better?

I've been there, when I was 16 in school the whole thing was a bloody farce, I didn't need varaible names, I didn't need comments, I didn't need to map out what my program was going to do-- but hell, turns out if I had nice flowing ability to design processes without having to write the code, I would have been able to write better programs faster. I had to stop, go back, and re-learn all that crap just to get my skills up to par.

Take advice from someone who thought his programming skills were hot shit when he was 16.

[Raynes]

0xFF, on 31 Jan, 2010 - 06:51 PM, said:

Here's the problem--
Are you going to be that guy the managers make fun of behind his back because he sits there and spins his propeller hat all day writing code with geek stamped on your head, taking instructions from the guy designing processes, or are you going to train yourself to be something better?

I've been there, when I was 16 in school the whole thing was a bloody farce, I didn't need varaible names, I didn't need comments, I didn't need to map out what my program was going to do-- but hell, turns out if I had nice flowing ability to design processes without having to write the code, I would have been able to write better programs faster. I had to stop, go back, and re-learn all that crap just to get my skills up to par.

Take advice from someone who thought his programming skills were hot shit when he was 16.

Here's the problem--

You need to stop acting like you're better than everybody else. I don't remember him ever saying he was highly skilled. Just because you were an idiot at 16 doesn't mean everybody else has to be.

@erik Stop aging for a little while, and I might catch up to you. I turn 16 day after tomorrow (the 2nd).

[macosxnerd101]

0xFF, on 31 Jan, 2010 - 10:38 PM, said:

Here's the problem-- When I hire you, your not going to have any practice with meaningful comments.

Here's the problem- you haven't hired us yet. When we get out into the working world, will we be able to appropriately comment our code? Yes. Why? B/c one- we've seen it before (on AP CS FRQs, on DIC, etc.), and two- we're more intelligent than trained monkeys on a pedestal (here's the problem with us being trained monkeys- Erik.price and I have both earned the Expert badge). It's those damn managerial types who don't understand what goes on behind the scenes that you have to worry about.

@Raynes: Well said.

This post has been edited by macosxnerd101: 31 January 2010 - 10:31 PM

[NickDMax]

Well I comment a lot... I use comments as a documentation tool and often provide usage examples etc.

I don't tend to put too many inline comments. I tend to try to write code in a way that it can be "read" and so I often feel that the logic is clear enough. but when it isn't I will add documentation. I also document anything like an empty block (actually I didn't used to do this but in code reviews that has been a common critique).

I have learned to ALWAYS keep code "professional" -- you never know when some smartass remark in code will turn up. Recently we had a big scare over a smart-ass log message. Turns out the comment came from Oracle and was in a bit of code that SHOULD have never run (i.e. it should have been one of those "dead code" blocks formed by a catch-block that should never have been able to run). -- I have to say the message, while I don't recall what it was, it did actually describe the situation and aided in troubleshooting... and since it was unique enough a google search was able to identify its source.

[0xFF]

macosxnerd101, on 31 Jan, 2010 - 11:31 PM, said:

Here's the problem- you haven't hired us yet. When we get out into the working world, will we be able to appropriately comment our code? Yes. Why? B/c one- we've seen it before (on AP CS FRQs, on DIC, etc.), and two- we're more intelligent than trained monkeys on a pedestal (here's the problem with us being trained monkeys- Erik.price and I have both earned the Expert badge). It's those damn managerial types who don't understand what goes on behind the scenes that you have to worry about.

@Raynes: Well said.

Raynes, on 31 Jan, 2010 - 10:46 PM, said:

Here's the problem--

You need to stop acting like you're better than everybody else. I don't remember him ever saying he was highly skilled. Just because you were an idiot at 16 doesn't mean everybody else has to be.

@erik Stop aging for a little while, and I might catch up to you. I turn 16 day after tomorrow (the 2nd).

You need to grow up and figure out when something is a personal attack and when something is advice. Who the hell do you think you are? "Just because you were an idiot at 16 doesn't mean everybody else has to be. " You can't even wrap your head around proper documentation being useful in the industry, so now we're mudslinging? What next, are you going to flame me, throw eraser bits at me, beat me up for my lunch money? This is the internet, it's serious business, so don't get so butthurt because I said documentation is important.

When the hell did I say I was better than everyone else? Did I say this because I said commenting is important when you want to be part of an actual team? Did I say I'm better than you because I have a job and experience in the industry? Did I say I'm better than you because I know what managers in tier 1 2 and 3 organizations look for, and how they think about their "it guy," and how they evaluate him?

Or am I better than you because I was trying to give you some advice that you disagreed with because it means you would have to change your philosophy on writing code?. No, it doesn't take a genius to figure out how to go

//This is an if block DERRRPPP MANAGERS DON'T KNOW WHAT IT IS LOLOL!!!!1 INTERNETS

But to know how to identify sections of code that are less obvious, so when YOU, or a co-worker, or you move on and your replacement comes to look at that code, they know what the hell you were trying to do without having to step through the thing.
A few lines of:

//This function takes __ which is __ and __ which is __, returning ___
//It does this by looping through __ and calling __.
func name(__, ___) {
variables //Hey this variable could be important

Will save time reading through it again in a few years when you need to change something. Metrics we use go something like this in this case: it takes about an hour to go through 500 lines of code you've never seen before to go back and comment it, just to figure out what they were trying to do. Do you know what a cost it is to us when we need to get a new guy to come in and clean up the mess left behind because you never got the second-nature of documenting your stuff? He can't hit the ground running because he has 20,000 lines of yours to go through. We have to spend a full week for him just to go through it and learn the program per 20,000 lines. We can use some techniques to fan through this crap faster-- but not all of the time.

I'm really sorry that you feel I'm some egomaniac on the internet who likes to scream at high school kids about their coding styles. My true intention was to give some light to you young guys on what I've actually dealt with AT REAL JOBS, or hey, even that thing called POST SECONDARY.

Yeah, I know it's not hard to put in a line of commenting, but if you're wasting my time because the new guy has to fan through thousands of lines of code to read it because "hey, It's those damn managerial types who don't understand what goes on behind the scenes LOL!!!!11," I won't want to use you again.

If you can't design something in UML, flow chart it, comment it, map it, psudocode it first, do something to model it before you write it so you can RTFM as you code, then you have something to document it with, I don't bloody want you. That's the end of the story. In real life, I don't care that you "have CSIII and know what you're talking about".

This post has been edited by 0xFF: 01 February 2010 - 05:50 PM

[macosxnerd101]

0xFF, on 1 Feb, 2010 - 08:49 PM, said:

I'm really sorry that you feel I'm some egomaniac on the internet who likes to scream at high school kids about their coding styles. My true intention was to give some light to you young guys on what I've actually dealt with AT REAL JOBS, or hey, even that thing called POST SECONDARY.

I don't think anyone here was disputing the validity of your point about proper documentation- far from it. It was more the tone in which you said it, which came across as more like a parent than a peer (and hey, we're 16 & 17, how well do you think we respond to our parents as it is. ). Plus, like I said, a lot of us that are in HS have taken or are in the AP CS class (and of course on DIC), which exposes us to documentation so we'll be prepared to document. But at the HS level, it's a different attitude. I personally would rather do Calculus HW that will help prepare me for the AP Calculus Exam in May and get a little downtime at night rather than taking the extra half-hour to comment code I'll probably never look at again, which will eat up my extra half-hour before bed. I think that most of us though will be able to adequately comment our code, and adapt to the standard that the company we work for has set (correct me if I'm wrong, but I'm pretty sure that different companies have different commenting protocols) when we get out into the working world, as commenting comes down to proper spacing (we've seen the to-do's from the AP CS FRQs and the do-nots on indentations from new DICs) and being able to describe a code segment to a certain degree.