incubator-s4-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Neumeyer <leoneume...@gmail.com>
Subject beautiful code
Date Thu, 20 Oct 2011 23:55:17 GMT
>From the 1985 Playboy Interview with Steve Jobs:

"When you're a carpenter making a beautiful chest of drawers, you're
not going to use a piece of plywood on the back, even though it faces
the wall and nobody will ever see it. You'll know it's there, so
you're going to use a beautiful piece of wood on the back. For you to
sleep well at night, the aesthetic, the quality, has to be carried all
the way through."

So make sure you can sleep at night when you write code!

I propose a few simple guidelines on comments:

* For consistency, let's follow standard Javadoc guidelines:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

* Write detailed documentation for public classes and methods (See
ProcessingElement).

* Good design will make the code easy to understand but eventually we
need to implement complex logic. For those cases write very detailed
comments to help other people read your code.

* Source code comments:

<pre>
/* Blah blah blah. */
                       ^
                       period
  ^
  capitalized

/*
 * Called when we create the first PE instance. TODO: Would be better to do
 * this as part of the PE lifecycle after PE construction.
 */

</pre>

* Use keyword TODO when there is something left to do, Eclipse will
list the TODOs.



--

-leo

Mime
View raw message