[KyOSS Discuss] Meeting Wednesday at new venue: Click IT Staffing

Ryan Hartlage ryanplusplus at gmail.com
Tue Jul 8 13:39:27 EDT 2014


@Deven, @Randy

Definitely agree with your points for interface comments (we use Doxygen,
ie: JavaDoc, for this).  Those guidelines are what I follow for
implementation/line-by-line comments.


On Tue, Jul 8, 2014 at 1:29 PM, Deven Phillips <deven.phillips at gmail.com>
wrote:

> FYI, I like the idea of using Vert.x for this project because it supports
> writing the code in many of the languages that this group has an interest
> in:
>
> Java
> Ruby
> Python
> Groovy
> PHP
> JavaScript
> Scala
> Clojure
>
> That means that almost everyone can be productive and helpful in
> contributing to the project...
>
> Anyone else have opinions?
>
> Deven
>
>
> On Tue, Jul 8, 2014 at 1:23 PM, Deven Phillips <deven.phillips at gmail.com>
> wrote:
>
>> I like Douglas Crockford’s JS style guidelines (from JavaScript: The
>> Good Parts, 94)...
>>
>> Excerpt:
>>
>> I indented the contents of blocks and object literals four spaces. I
>> placed a space between if and ( so that the if didn't look like a
>> function invocation. Only in invocations do I make ( adjacent with the
>> preceding symbol. I put spaces around all infix operators except for .
>>  and [, which do not get spaces because they have higher precedence. I
>> use a space after every comma and colon.
>>
>> I put at most one statement on a line. Multiple statements on a line can
>> be misread. If a statement doesn't fit on a line, I will break it after a
>> comma or a binary operator. That gives more protection against copy/paste
>> errors that are masked by semicolon insertion. (The tragedy of semicolon
>> insertion will be revealed in Appendix A
>> <http://my.safaribooksonline.com/9780596517748/awful_parts#awful_parts>.)
>> I indent the remainder of the statement an extra four spaces, or eight
>> spaces if four would be ambiguous (such as a line break in the condition
>> part of an if statement).
>>
>> I always use blocks with structured statements such as if and while because
>> it is less error prone. I have seen:
>>
>> if (a)
>>     b(  );
>>
>> become:
>>
>> if (a)
>>     b(  );
>>     c(  );
>>
>> which is an error that is very difficult to spot. It looks like:
>>
>> if (a) {
>>     b(  );
>>     c(  );
>> }
>>
>> but it means:
>>
>> if (a) {
>>     b(  );
>> }
>> c(  );
>>
>> Code that appears to mean one thing but actually means another is likely
>> to cause bugs. A pair of braces is really cheap protection against bugs
>> that can be expensive to find.
>>
>> I always use the K&R style, putting the { at the end of a line instead
>> of the front, because it avoids a horrible design blunder in JavaScript's
>> return statement.
>>
>> I included some comments. I like to put comments in my programs to leave
>> information that will be read at a later time by people (possibly myself)
>> who will need to understand what I was thinking. Sometimes I think about
>> comments as a time machine that I use to send important messages to future
>> me.
>>
>> I struggle to keep comments up-to-date. Erroneous comments can make
>> programs even harder to read and understand. I can't afford that.
>>
>> I tried to not waste your time with useless comments like this:
>>
>> i = 0; // Set i to zero.
>>
>> In JavaScript, I prefer to use line comments. I reserve block comments
>> for formal documentation and for commenting out.
>>
>> I prefer to make the structure of my programs self-illuminating,
>> eliminating the need for comments. I am not always successful, so while my
>> programs are awaiting perfection, I am writing comments.
>>
>> JavaScript has C syntax, but its blocks don't have scope. So, the
>> convention that variables should be declared at their first use is really
>> bad advice in JavaScript. JavaScript has function scope, but not block
>> scope, so I declare all of my variables at the beginning of each function.
>> JavaScript allows variables to be declared after they are used. That feels
>> like a mistake to me, and I don't want to write programs that look like
>> mistakes. I want my mistakes to stand out. Similarly, I never use an
>> assignment expression in the condition part of an if because:
>>
>> if (a = b) { ... }
>>
>> is probably intended to be:
>>
>> if (a === b) { ... }
>>
>> I want to avoid idioms that look like mistakes.
>>
>> I never allow switch cases to fall through to the next case. I once found
>> a bug in my code caused by an unintended fall through immediately after
>> having made a vigorous speech about why fall through was sometimes useful.
>> I was fortunate in that I was able to learn from the experience. When
>> reviewing the features of a language, I now pay special attention to
>> features that are sometimes useful but occasionally dangerous. Those are
>> the worst parts because it is difficult to tell whether they are being
>> used correctly. That is a place where bugs hide.
>>
>
>
> _______________________________________________
> KyOSS-Discuss mailing list
> KyOSS-Discuss at kyoss.org
> Subscribe by sending email to kyoss-discuss-subscribe at kyoss.org
> Unsubscribe by sending email (from the address you wish to unsubscribe) to
> kyoss-discuss-unsubscribe at kyoss.org
> Difficulty unsubscribing? Check your email headers for originally-to
> address in case you are forwarding your mail.
> More options at http://kyoss.org/cgi-bin/mailman/listinfo/kyoss-discuss
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://kyoss.org/pipermail/kyoss-discuss/attachments/20140708/d8157864/attachment-0001.html>


More information about the KyOSS-Discuss mailing list