HTML5 Canvas for Dummies
  • HTML5 Canvas For Dummies
    HTML5 Canvas For Dummies
    by Don Cowan
Search Our Site
Contact

tel. 970 708 0899

fax. 970 497 4377

contact@marketimpacts.com

Email Us
This form does not yet contain any fields.
    Search Our Website
    This area does not yet contain any content.
    Free QuickClick App Downloads

    Click below to download free QuickClick apps for your Android smartphone... 

    ATM

     

    Auto

     

    Casinos

     

    Coffee

     

    Dessert

     

    English Places

     

    Fast Food

     

    French Places

     

    Gas

     

    Golf

     

    Health Food

     

    Irish Places

     

    Italian Places

     

    Lodging

     

    Mail

     

    Nightlife

     

    Parking

     

    Restaurants

     

    RV

     

    Scottish Places

     

    Shopping 

     

    Taxi


    Truck

    Custom Apps

    Get a custom QuickClick app for your business. Use the format you see here or let us create a custom format tailored to your needs.

      

    « Software Application Re-use | Main | What is HTML5 Canvas? »
    Tuesday
    Sep252012

    Code Comments

    What makes good code comments? Should they be terse or expansive? Should they be frequent or used sparingly? Opinions on these and other aspects of code commenting vary widely. My take is this ... to answer these questions, start with the objectives for code comments:

    To assist in development: Comments aid in understand functionality being implemented in code. For example, they can be used as pseudo-code place holders for eventual real code.

    To speed development and maintenance: Comments allow more rapid digestion of code sections. This is especially important when revisiting code not recently seen or code developed by others.

    To clarify code: The function of a section of even well constructed code may not be evident. Comments can add that critical piece of missing information.

    Given these objectives, here are some suggestions:

    Comment appropriate groups of code: Sometimes a single line of code might need explanation. Or there might be a long section of code that repeats similar functionality and a single comment will suffice for the group. It's a judgment call.

    Leave signposts for developers: Even if a section of code can be understood without a comment, how long will it take for you, or someone else, to understand it after time passes? Also, it's sometimes important to be able to understand the flow of a function or application without necessarily understanding all the details. Give yourself and others a break, make understanding as easy as possible. Most code is not a programming quiz.

    Clean up comments: Keep them up to date and free of extraneous information. Remove temporary words used during development. Make them understandable. After all, that's their purpose in life.

    Add comments while coding: It's tempting to think you can go back later and add a comment to some code that looks perfectly clear to you as you write it. Don't do it. Leverage the knowledge you have in that temporary cache in your brain.

    Use a fairly uniform comment style: You don't have to be perfectly uniform, but it's a good idea to used some consistency within an application. It helps with understanding and looks more professional. 

    Add value to the code being commented: Don't just repeat what the code obviously tells you. Make the comment compliment and add value to the code.

    PrintView Printer Friendly Version

    EmailEmail Article to Friend

    References (2)

    References allow you to track sources for this article, as well as articles that were written in response to this article.

    Reader Comments

    There are no comments for this journal entry. To create a new comment, use the form below.

    PostPost a New Comment

    Enter your information below to add a new comment.

    My response is on my own website »
    Author Email (optional):
    Author URL (optional):
    Post:
     
    Some HTML allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <code> <em> <i> <strike> <strong>