Commenting code

Download
Share  Add to  Flag Embed
Views:
 
Category: Education
     
 
License:   All Rights Reserved

Presentation Description

There are different approaches about commenting code, ranging from ignoring comments to commenting everything you can. Paradoxically, the issue is that important because comments seem to be so much insignificant comparing to the real code. All decisions about whether to comment or not should be as quick as possible and the price of revisiting a decision is high.

Comments

Presentation Transcript

Slide 1: 

commenting code Andrew Kazyrevich

Slide 2: 

© Kris Van Beek

Slide 3: 

///<summary> /// 0 - parentId, /// 1 – postbackUrl, /// 2 – container, /// 3 – default uploader ///</summary> private const string template = @"{0}=new Uploader ('{0}','{1}','{2}','{3}');"; ... string script = string.Format(template, ClientID, ...); AddJavascript(script);

Slide 4: 

private const string template = @"{0}=new Uploader ( {{ parentId: '{0}', postbackUrl: '{1}', container: '{2}', defaultUploader: '{3}' }});"; ... string script = string.Format(template, ClientID, ...); AddJavascript(script);

why do we use comments? : 

why do we use comments?

source of hidden information : 

© Banca Immagine source of hidden information

deodorant for bad code smell : 

deodorant for bad code smell

how to distinguish? : 

how to distinguish?

dark side of things : 

dark side of things

Slide 11: 

//open the file var file = File.Open(…); … using(var scope = new TransactionScope()) { … //saving the changes scope.Complete(); }

commenting the obvious : 

commenting the obvious

increased code noise : 

increased code noise

maintenance burden : 

maintenance burden

Slide 15: 

© Tim Maher

self-documenting code : 

self-documenting code

good taste : 

good taste

bad code… : 

bad code…

Slide 20: 

© Saddington & Baynes

…is one of the reasonsfor comments : 

…is one of the reasonsfor comments

remedy:refactoring : 

remedy:refactoring

Slide 23: 

local variables sub-routines

Slide 24: 

BUT

bright side of things : 

bright side of things

Slide 26: 

comments help the team to use the code

Slide 27: 

comments work with self-documenting code

Slide 28: 

…on a higher level

Slide 30: 

code explains how comments explain why

Slide 31: 

//explain the need for the type, //clarify usage scenarios and //specific design decisions class Customer { … } struct Point { … } enum Direction { … }

Slide 32: 

//outline design contract, //specify in/out restrictions //and fault conditions for methods interface IEngine { … }

Slide 33: 

//explain complex decisions, //unobvious bug fixes and //workarounds, performance hints Some code = Goes.Here; Need comment = yes ? true : false;

Slide 34: 

as brief as possible but as detailed as needed

use complete sentences : 

use complete sentences

do not curse : 

do not curse

spel chek : 

spel chek

correct invalid comments : 

correct invalid comments

http://codevanced.net : 

http://codevanced.net

questions : 

questions

The End : 

The End