Writing documentation and coding style

Best practices always encourage you to document your code through the use of comments. A programmer might create a working program today, see it used for months or years, and then have to make changes to it. Programming languages are fairly cryptic, there are many of them, each with its own syntax and semantic differences, and if the program is complex, even the original author will struggle to understand what the code was meant to do. Comments provide the opportunity to describe, in plain text, what the program does and how it works.

Writing code

Code must be neat and organized to be easy to read and easy to debug. Best practices include indentation and new line for each statement. Also note text editors provide syntax highlighting, indentation, line numbers, and mono-spaced font to make the code easier to read.

When sharing code on paper or electronically (PDF), include line numbers, print single-line spacing, use mono-spaced font, preserve indentation, and color syntax (whenever possible). Every printed document must have header and footer, which provide author's name on every page, name of the document on every page, and page number (preferably in the format "Page X of Y" (especially for longer printouts).

Documenting code

Every code file (regardless of language) must have inline documentation, whether or not there is external or more formal documentation (specs, design, guides,...) being prepared. At minimum, include header (sometimes called prologue) at the top of each file; specify the author(s), date file created, date last modified, original file name, short description (purpose), optionally pseudo-code when appropriate.

Add appropriate header. Always include header (prologue) after the <meta charset=...> element in HTML (in other languages you included at the beginning of the file or after any directives)


<!-- 
Author:       Your Name
Program:      pageName.html
Date:         [date created]
Updated:      [date last updated] 
Version:      0.0
Purpose:      short description what the page (site) is all about
Description:  describe the solution in detail 
              (include algorithm if applicable)
              - focus on the "why"
-->

Use comments to describe the code precisely and completely.

Use comments in addition to the meta element for describing the document.

DO NOT PUT comments before the DOCTYPE declaration. Place comments inside the head and body sections only.

Include meaningful observations and specifications throughout the document.


<!-- Browsers automatically add some white space (a margin)
 before and after a paragraph, but ignore whitespace 
 inside the paragraph.-->
<p>
This paragraph
	contains a lot of lines
		in the source code,
but 	the					 browser 
ignores it.
</p>

Using existing code

Do not use any code you do not understand. Do not rely on copy and paste technique to complete your work. If you are working with other people's code, make sure you document well what the code does, who created, where you found it, and what changes you made to it (if any).

What does w3schools say about the following?

Use Correct Document Type
Use Lowercase Element Names
Close All HTML Elements
Use Lowercase Attribute Names
Always Quote Attribute Values
Always Specify alt, width, and height for Images
Spaces and Equal Signs
Avoid Long Code Lines
Blank Lines and Indentation
Never Skip the title Element
Omitting html> and body?
Omitting head?
Close Empty HTML Elements?
Meta Data
Setting The Viewport

What does google say about the following? Have a closer look at the following sections: