RSS

Documentation comments in code




  • When modifying code, always keep the commenting around it up to date.


  • At the beginning of every routine, it is helpful to provide standard, boilerplate comments, indicating the routine's purpose, assumptions, and limitations. A boilerplate comment should be a brief introduction to understand why the routine exists and what it can do.


  • Avoid adding comments at the end of a line of code; end-line comments make code more difficult to read. However, end-line comments are appropriate when annotating variable declarations. In this case, align all end-line comments at a common tab stop.


  • Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.


  • Avoid surrounding a block comment with a typographical frame. It may look attractive, but it is difficult to maintain.


  • Prior to deployment, remove all temporary or extraneous comments to avoid confusion during future maintenance work.


  • If you need comments to explain a complex section of code, examine the code to determine if you should rewrite it. If at all possible, do not document bad code—rewrite it. Although performance should not typically be sacrificed to make the code simpler for human consumption, a balance must be maintained between performance and maintainability.


  • Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.


  • Comment as you code, because most likely there won't be time to do it later. Also, should you get a chance to revisit code you've written, that which is obvious today probably won't be obvious six weeks from now.


  • Avoid the use of superfluous or inappropriate comments, such as humorous sidebar remarks.


  • Use comments to explain the intent of the code. They should not serve as inline translations of the code.


  • Comment anything that is not readily obvious in the code.


  • To prevent recurring problems, always use comments on bug fixes and work-around code, especially in a team environment.


  • Use comments on code that consists of loops and logic branches. These are key areas that will assist the reader when reading source code.


  • Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.


  • Throughout the application, construct comments using a uniform style, with consistent punctuation and structure.


  • Despite the availability of external documentation, source code listings should be able to stand on their own because hard-copy documentation can be misplaced or may not answer the details and intent of the developer(s).


  • External Documentation:


  • External documentation should consist of specifications, design documents, change requests, bug history, and the coding standard that was used.

0 comments

Posted in

Extracting HTML source from a URL website


Was just thinking of trying something short and sweet and thought of trying out a snippet for extracting code from the entered url.
Following is the code have not declared the namespaces on top but used them directly in the code to bring more clarity on which namespace the object comes from.

The code is self explanatory so wont add any explanations over here..

</// <summary>
/// Extracts the source from the url entered.
/// </summary>
/// <param name="url">url to fetch the source from.</param>
/// <returns>string: source for the url entered.</returns>
public static string GetHtmlPageSource(string url)
{

System.IO.Stream st = null;
System.IO.StreamReader sr = null;

try
{
// make a Web request
System.Net.WebRequest req = System.Net.WebRequest.Create(url);

// get the response and read from the result stream
System.Net.WebResponse resp = req.GetResponse();
st = resp.GetResponseStream();
sr = new System.IO.StreamReader(st);
// read all the text in it
return sr.ReadToEnd();
}
catch (Exception ex)
{
return string.Empty;
}
finally
{
// close the stream & reader objects.
sr.Close();
st.Close();
}
}



UPDATE:

If you need to authenticate the request use the following just before you make the request to read the source

// authenticate using the credentials passed for getting access to the page.
if (username != null && password != null)
req.Credentials = new System.Net.NetworkCredential(username, password);
// get the response and read from the result stream
.
.
.
Copyright © Shounak S. Pandit. Powered by Blogger.

Ads