A Comment on Comments - Revision history

Kevlin at 11:06, 10 July 2009

Kevlin — Fri, 10 Jul 2009 11:06:20 GMT

←Older revision		Revision as of 11:06, 10 July 2009
Line 1:		Line 1:
-	In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read "Write a program to input and average 10 bowling scores." Then the teacher left the room. How hard could this be? I don't remember my final solution but I'm sure it had a <code>FOR</code>/<code>NEXT</code> loop in it and couldn't have been more than 15 lines long total. Coding sheets — for you kids reading this, yes, we used to write code out longhand before actually entering it into a computer — allowed for around 70 lines of code each. I was very confused as to why the teacher would have given us two sheets. Since my handwriting has always been atrocious, I used the second one to re-copy my code very neatly, hoping to get a couple extra points for style.	+	In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read "Write a program to input and average 10 bowling scores." Then the teacher left the room. How hard could this be? I don't remember my final solution but I'm sure it had a <code>FOR</code>/<code>NEXT</code> loop in it and couldn't have been more than 15 lines long in total. Coding sheets — for you kids reading this, yes, we used to write code out longhand before actually entering it into a computer — allowed for around 70 lines of code each. I was very confused as to why the teacher would have given us two sheets. Since my handwriting has always been atrocious, I used the second one to re-copy my code very neatly, hoping to get a couple extra points for style.

	Much to my surprise, when I received the assignment back at the start of the next class, I received a barely passing grade. (It was to be an omen to me for the rest of my time in college.) Scrawled across the top of my neatly copied code, "No comments?"		Much to my surprise, when I received the assignment back at the start of the next class, I received a barely passing grade. (It was to be an omen to me for the rest of my time in college.) Scrawled across the top of my neatly copied code, "No comments?"
Line 5:		Line 5:
	It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It's a lesson I've not forgotten.		It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It's a lesson I've not forgotten.

-	Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to ''javadoc'' that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. ~~Sprinkled inside~~ your code should be explanations to what the code is supposed to be doing. Coding by the old adage, "If it was hard to write, it should be hard to read," does a disservice to your client or employer.	+	Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to ''javadoc'' that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. Inside your code should be explanations about what the code is supposed to be doing. Coding by the old adage, "If it was hard to write, it should be hard to read," does a disservice to your client, your employer, your colleagues, and your future self.

	On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but do not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.		On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but do not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.

-	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually ~~review~~ the code as it's committed. It was my first introduction to the term ''career-limiting move''.	+	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually reviewed the code when it was committed. It was my first introduction to the term ''career-limiting move''.

	by [[Cal Evans]]		by [[Cal Evans]]

Kevlin at 12:33, 4 February 2009

Kevlin — Wed, 04 Feb 2009 12:33:10 GMT

←Older revision		Revision as of 12:33, 4 February 2009
Line 5:		Line 5:
	It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It's a lesson I've not forgotten.		It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It's a lesson I've not forgotten.

-	Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to ~~<code>~~javadoc~~</code>~~ that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. Sprinkled inside your code should be explanations to what the code is supposed to be doing. Coding by the old adage, "If it was hard to write, it should be hard to read," does a disservice to your client or employer.	+	Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to ''javadoc'' that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. Sprinkled inside your code should be explanations to what the code is supposed to be doing. Coding by the old adage, "If it was hard to write, it should be hard to read," does a disservice to your client or employer.

-	On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.	+	On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but do not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.

-	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually review the code as it's committed. It was my first introduction to the term ''~~Career~~-~~Limiting Move~~''.	+	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually review the code as it's committed. It was my first introduction to the term ''career-limiting move''.

	by [[Cal Evans]]		by [[Cal Evans]]

Calevans at 15:39, 22 December 2008

Calevans — Mon, 22 Dec 2008 15:39:37 GMT

←Older revision		Revision as of 15:39, 22 December 2008
Line 9:		Line 9:
	On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.		On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.

-	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use ~~this~~ design into the header comment block of the file. It turns out that managers at this particular shop actually review the code as it's committed. It was my first introduction to the term ''Career-Limiting Move''.	+	At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually review the code as it's committed. It was my first introduction to the term ''Career-Limiting Move''.

	by [[Cal Evans]]		by [[Cal Evans]]

Calevans: New page: In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read "Write a program to input and average 10 bowling scores." Then t...

Calevans — Sun, 21 Dec 2008 09:26:53 GMT

New page: In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read "Write a program to input and average 10 bowling scores." Then t...

New page

In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read "Write a program to input and average 10 bowling scores." Then the teacher left the room. How hard could this be? I don't remember my final solution but I'm sure it had a <code>FOR</code>/<code>NEXT</code> loop in it and couldn't have been more than 15 lines long total. Coding sheets — for you kids reading this, yes, we used to write code out longhand before actually entering it into a computer — allowed for around 70 lines of code each. I was very confused as to why the teacher would have given us two sheets. Since my handwriting has always been atrocious, I used the second one to re-copy my code very neatly, hoping to get a couple extra points for style.

Much to my surprise, when I received the assignment back at the start of the next class, I received a barely passing grade. (It was to be an omen to me for the rest of my time in college.) Scrawled across the top of my neatly copied code, "No comments?"

It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It's a lesson I've not forgotten.

Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to <code>javadoc</code> that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. Sprinkled inside your code should be explanations to what the code is supposed to be doing. Coding by the old adage, "If it was hard to write, it should be hard to read," does a disservice to your client or employer.

On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it while your in-line comments should assist the next developer in fixing or extending it.

At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use this design into the header comment block of the file. It turns out that managers at this particular shop actually review the code as it's committed. It was my first introduction to the term ''Career-Limiting Move''.

by [[Cal Evans]]

This work is licensed under a
[http://creativecommons.org/licenses/by/3.0/us/ Creative Commons Attribution 3]

Back to [[97 Things Every Programmer Should Know]] home page