PAB Skunkworks Weblog

March 6, 2013

Tagging the Web Daily 03/07/2013

Filed under: Uncategorized — happyfunball96 @ 5:30 pm
    • Code can communicate “what” it does. But only comments can communicate “why” it does it! “why” is a broader truth that simply cannot be expressed in code. It involves requirements, feelings, experience
      • Good design (and thus documentation) rules to reach conciseness are these:

          

        • Don’t let methods with more than 3 arguments leak into your public API.
        • Don’t let methods / types with more than 3 words in their names leak into your public API.

         

        Best avoid the above. If you cannot avoid such methods, keep things private. These methods are not reusable and thus not worth documenting in an API.

      • Keep things simple and concise

        Create good documentation:
          

        • by keeping documentation simple and concise.
        • by keeping documentation close to the code and close to the API, which are the ultimate truths of your application.
        • by keeping your documentation DRY.
        • by making documentation available to others, through a ticketing system,version controlsemantic versioning.
        • by referencing ticket IDs throughout your available media.
        • by forgetting about “external” documentation, as long as you can.
    • Brittle Software and the Game of Jenga
    • software that has thought-to-be-dead code that no one dares remove or code that desperately needs refactoring but involves too much risk to be refactored.
    • many software projects seem to go through the Jenga game lifecycle. Changes are easy at first in both cases but become increasingly difficult and risky as the game or project goes on and the structure (Jenga tower or project code base) becomes unwieldy.
    • Concurrent or Not: Nine Women Making a Baby in One Month

      Fred Brooks wrote in The Mythical Man-Month the well-known quotation that “The bearing of a child takes nine months, no matter how many women are assigned.”

    • Ignoring Warnings: Sweeping Dirt Under the Rug or Hiding Junk in the Closet
    • Comments are Deodorant for Stinky Code
    • some comments have value (such as Javadoc methods describing pre-conditions and post-conditions and other contract details), but in-method comments often do seem to be extraneous or redundant at best, downright misleading or out-of-date in other cases, or must exist because the code they describe is inscrutable without them

Posted from Diigo. The rest of my favorite links are here.

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

The Rubric Theme. Create a free website or blog at WordPress.com.

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: