Comments on: The Art of Writing Code http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/ Malaysia website design blog Sat, 04 Feb 2012 04:00:00 +0000 hourly 1 http://wordpress.org/?v=3.3.1 By: Hawk http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/comment-page-1/#comment-1039 Hawk Tue, 23 May 2006 13:53:03 +0000 http://pWhenpeoplethinkofwritingcode,theyoftenjustthinkofitaswritinginstructionstoperformacertainfunction.Littlecareisoftengiventohowthecodeispresented.Youmayask,what'sthepoint?What'sthedifference?Afterall,thecodesti#comment-1039 Exactly why i said only keep comments for complex code :). Much too often you'll see comments like this: <blockquote>/* Loop to find if a value exists in array */</blockquote> Such comments are pretty pointless. If the code is performing a simple procedure, then it should easily describe itself. Even for "why" that code is being used, it should only be written for good reason. Saying: <blockquote>/* Used a bubble sort because I don't know how to write a better sorting algorithm */</blockquote> is bad since it doesn't help us in any way. But writing: <blockquote>/* Added (code) to fix a BUG 1007 which caused memory leaks when (condition) */</blockquote> is acceptable. This provides information which you might not have known from just seeing the code. As for more efficient ways... only our experience can help us in that. Comments won't do much much really. Exactly why i said only keep comments for complex code :) . Much too often you’ll see comments like this:

/* Loop to find if a value exists in array */

Such comments are pretty pointless. If the code is performing a simple procedure, then it should easily describe itself.

Even for “why” that code is being used, it should only be written for good reason. Saying:

/* Used a bubble sort because I don’t know how to write a better sorting algorithm */

is bad since it doesn’t help us in any way. But writing:

/* Added (code) to fix a BUG 1007 which caused memory leaks when (condition) */

is acceptable. This provides information which you might not have known from just seeing the code.

As for more efficient ways… only our experience can help us in that. Comments won’t do much much really.

]]> By: Sashi http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/comment-page-1/#comment-1038 Sashi Tue, 23 May 2006 09:14:45 +0000 http://pWhenpeoplethinkofwritingcode,theyoftenjustthinkofitaswritinginstructionstoperformacertainfunction.Littlecareisoftengiventohowthecodeispresented.Youmayask,what'sthepoint?What'sthedifference?Afterall,thecodesti#comment-1038 I disagree with your opinions on comments. Good comment blocks aren't about describing procedures. It's about explaining why a piece is being used, and what is expected to be achieved. If I read someone's well-written code (without comments), sure I'll be able to understand what he's doing - but why did he use that code? Is there a more efficient way? None of these questions can be answered with good coding. I disagree with your opinions on comments. Good comment blocks aren’t about describing procedures. It’s about explaining why a piece is being used, and what is expected to be achieved. If I read someone’s well-written code (without comments), sure I’ll be able to understand what he’s doing – but why did he use that code? Is there a more efficient way? None of these questions can be answered with good coding.

]]> By: Hawk http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/comment-page-1/#comment-1037 Hawk Tue, 23 May 2006 08:58:36 +0000 http://pWhenpeoplethinkofwritingcode,theyoftenjustthinkofitaswritinginstructionstoperformacertainfunction.Littlecareisoftengiventohowthecodeispresented.Youmayask,what'sthepoint?What'sthedifference?Afterall,thecodesti#comment-1037 That's pretty useless.... in ANY editor you'll have a find function. Use it :) If you wrote your code properly, segments should be easy to find since you named them well. If you're using an IDE, some have code folding so the code isn't one big lump. If it doesn't have that feature, IDEs will often list out functions and classes used. It would be easy to jump around. That said, if your code is too frigging long you probably need to refactorise your code somewhere. Break it out into smaller more manageable pieces. Comments should only be used in 2 cases. 1) To describe a complex procedure 2) To generate documentation ala phpDoc or JavaDoc That’s pretty useless…. in ANY editor you’ll have a find function. Use it :) If you wrote your code properly, segments should be easy to find since you named them well.

If you’re using an IDE, some have code folding so the code isn’t one big lump. If it doesn’t have that feature, IDEs will often list out functions and classes used. It would be easy to jump around.

That said, if your code is too frigging long you probably need to refactorise your code somewhere. Break it out into smaller more manageable pieces.

Comments should only be used in 2 cases.

1) To describe a complex procedure
2) To generate documentation ala phpDoc or JavaDoc

]]> By: David http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/comment-page-1/#comment-1036 David Tue, 23 May 2006 01:26:54 +0000 http://pWhenpeoplethinkofwritingcode,theyoftenjustthinkofitaswritinginstructionstoperformacertainfunction.Littlecareisoftengiventohowthecodeispresented.Youmayask,what'sthepoint?What'sthedifference?Afterall,thecodesti#comment-1036 Good article Hawk! I've got something to say about comments too: Comments is cool. If you've got a lot of code, like pages and pages, comment headings can help you find the section you are looking for quickly, e.g. <code><big>/* ##### Section name ##### */</big></code> This serves as a visual marker so you can quickly scan your code, and not have to read it, so that you can find what you are looking for quickly. Good article Hawk!

I’ve got something to say about comments too: Comments is cool.

If you’ve got a lot of code, like pages and pages, comment headings can help you find the section you are looking for quickly, e.g.

/* ##### Section name ##### */

This serves as a visual marker so you can quickly scan your code, and not have to read it, so that you can find what you are looking for quickly.

]]> By: Hawk http://www.dannyfoo.com/blog/website-development/the-art-of-writing-code/comment-page-1/#comment-1035 Hawk Mon, 22 May 2006 08:43:33 +0000 http://pWhenpeoplethinkofwritingcode,theyoftenjustthinkofitaswritinginstructionstoperformacertainfunction.Littlecareisoftengiventohowthecodeispresented.Youmayask,what'sthepoint?What'sthedifference?Afterall,thecodesti#comment-1035 <blockquote>"well, the statements are actually for common cases… if your code is more concerntrated to its security, it’s naming & formatting should be misterious enough, to prevent hacking… ^^"</blockquote> Not really, that is just security through obscruity. Your code itself should be strong enough that even when people see and understand it, it will be hard to break. This is why the best encryption techniques are those that are open. It has to be reviewed by others to verify its strength. <blockquote>"Don’t forget to add comments in your code! ;)"</blockquote> I purposely left comments out :) The purpose of this article is to show that your code is self documented. The code explains itself. You should only add comments to really complex code which gives the person a better understanding on what the heck you're doing. Comments have the tendency of being out-of-date. Your code however will always be up to date. So only write comments if you have to, otherwise leave them out.

“well, the statements are actually for common cases… if your code is more concerntrated to its security, it’s naming & formatting should be misterious enough, to prevent hacking… ^^”

Not really, that is just security through obscruity. Your code itself should be strong enough that even when people see and understand it, it will be hard to break.

This is why the best encryption techniques are those that are open. It has to be reviewed by others to verify its strength.

“Don’t forget to add comments in your code! ;) ”

I purposely left comments out :)
The purpose of this article is to show that your code is self documented. The code explains itself. You should only add comments to really complex code which gives the person a better understanding on what the heck you’re doing.

Comments have the tendency of being out-of-date. Your code however will always be up to date. So only write comments if you have to, otherwise leave them out.

]]>