Code Readability: guide for writing your code jbwyatt.com

Code Readability


"Professional software developers spend most of their time trying to understand code. Moreover, maintenance can typically be expected to consume 70-90% of the total lifecycle budget of a software project. Maintaining and evolving high-quality documentation is crucial to help developers understand and modify code." [Buse & Weimer, ASE '10 Proceedings ]
"Good comments don't repeat the code or explain it -- they clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do." [Code Complete]
"Don't document bad code - rewrite it." [Code Complete]
"I just began working on a project that is pretty much a rewrite of an entire system because of sloppy, poorly documented code. Please stress to your students the importance of good documentation." [message from a former student, Feb, 2010]

If your code is unmaintainable, you are a liability. The majority of a software system's cost is consumed by maintenance which includes fixing problems, adapting code to new environments and adding functionality. The readability of the program directly affects maintainability.

            Examples from the trenches: google C++ style | google JavaScript style | StartupCTO | emboss | drupal

Code Refactoring

Refactoring is a continuous process improving the structure and maintainability of your code - not the functionality.
  - right-click on a highlighted variable or method name and click on "refactor" to change the name
  - right-click on a highlighted code block and click on refactor to "extract" a method
MSDN on Refactoring    |    A Refactoring Manifesto!

  Code Standards: C#, C++, JavaScript, Assembly

Header: THREE components.

  1. Identification:   Name / Date / Class
  2. Purpose:   Why is the program being written? What problem does it solve? A few sentences or a paragraph here.
  3. Algorithm / Overview:
    The steps you are going to take to solve the problem. Put some details here!.
    Write in bullets - not prose-style rambling... This is your plan of attack!

Body: FOUR components

  1. Meaningful Names: variables, constants and functions.
    Names should reflect the purpose they have.
  2. Indent: indent code in loops and if statements.
  3. White Space: use horizontal and vertical white space to make code readable.
  4. Comments: explain WHY. Don't repeat the obvious. Insight!

Additional Functions / Methods:

  1. Identification:   Name / Date / Class (if in separate file)
  2. Purpose: Simple statement of what the function/method does AT THE TOP
  3. Indent, Naming, White Space, Comments

Examples:
    C# Console: GlazerCalc1.cs   |   GlazerCalc2.cs
    C# Windows: FF.cs
    C++ Console: Metric.cpp   |   Dice.cpp
    Assembly: Template.asm
    JavaScript: js - see CODE section (1/3 down)

  Code Standards: HTML, CSS

Header: TWO components

  1. Identification:   Name / Date / Class
  2. Purpose:   Why is the page being created? Purpose? A few sentences or a paragraph here.

Body: FOUR components

  1. Meaningful Names: CSS CLASS names and ID names should reflect the content.
  2. Indent: indent the HTML and CSS to reflect the organization.
  3. White Space: Use both horizontal and vertical white space to make it readable.
  4. Comments: explain:
      HTML blocks (< div > , < h1-h6 > , < p >) <!-- comment -->
      CSS classes or ids. /* comment */

Examples:
    Web HTML: beautiful code  |  png image(needs a few commnents)
    Web CSS:   base.css


valid xhtml 1.0