On Sun, 20 Jun 2010, William "Chops" Westfield wrote:

> 
> On Jun 20, 2010, at 1:04 PM, sergio masci wrote:
> 
> > stating the obvious
> 
> Ah; I think I begin to see.  The following three lines of code do the  
> same thing, but are of increasing "goodness" due to meaning being  
> moved from comments to code.  The first line is somewhat typical.  The  
> second line uses a more meaningfully name temporary variable and  
> recasts the constant as hex to make the bits used more obvious.  And  
> the third line pretty much says everything that needs to be said,  
> without a comment (but you need to have written a trustworthy macro or  
> subroutine at some point.  Some people would claim that this goes too  
> far.)
> 
> 	c = pak.iphdr.saddr & 192;   /* mask upper bits to get network class */
> 	netclass = pak.iphdr.saddr & 0xC0;  /* get network class */
> 	netclass = GET_NETWORK_CLASS(pak);
> 

Yes but it's not only the fact that you've removed the comment that is 
important - you've also attached meaning to that fraction of code (not 
only for yourself or another person BUT ALSO FOR THE COMPILER).

Say while you are defining GET_NETWORK_CLASS you think to yourself "there 
really should be a coressponding SET_NETWORK_CLASS" so you define it as 
well. GET_NETWORK_CLASS and SET_NETWORK_CLASS now have a relationship and 
this makes it easier for you to maintain both when you make changes to 
either. They don't need to be macros they could be proper functions.
The relationship could be something as simple as a convention you've 
invented (e.g. for every GET_xxx there needs to be a SET_xxx).

If you only had line types (1) or (2) in your code you would need to hunt 
through your code for anywhere that might "set up the network class" when 
you change the code that "gets the network class". You might have to rely 
on searching through comments but there is nothing that guarentees the 
correctness or even the existance of a comment you could home in on!

trying to make something that trips the compiler or assembler when you 
make a BAD change is key (you simply can't do this with comments).

Say you did something like

	a = FUNC(b, c)

and you did this all over your code. Now for some reason you need to 
change *SOME* of these to

	b = FUNC_B(a, c)

How would you ensure that you checked each one? How would you give 100% 
guarentee that you've done all the work correctly (let's say a life 
depends on it)? Personnaly I would change the name of FUNC to FUNC_A then 
as I went through and checked each use of FUNC I would change the use from 
FUNC to either FUNC_A or FUNC_B. Now if the code wont compile I know there 
is a problem.

Ok, what has this to do with GET_NETWORK_CLASS you ask. Well in the same 
way that you can get the compiler to trip when you rename FUNC to FUNC_A, 
you can get the compiler to trip when you change GET_NETWORK_CLASS to 
GET_NETWORK_CLASS_x. You can't do this with COMMENTS! Of course, once 
you've finished playing about with GET_NETWORK_CLASS_x, you can simply 
rename it back to GET_NETWORK_CLASS.

Ok so how to you ensure that SET_NETWORK_CLASS gets updated when 
GET_NETWORK_CLASS is modified? You either need something shared by both so 
that changing GET_NETWORK_CLASS and the shared item causes the compiler to 
trip while it's working through SET_NETWORK_CLASS (maybe a 
NETWORK_CLASS_FUNC_NEEDS_CHANGING macro which gets changed to 
NETWORK_CLASS_FUNC_NEEDS_CHANGING_X) or you need to rely on a comment. I 
didn't say you can't use comments just that you are trying to greatly 
reduce your dependence on them and only put them in where they are 
necessary.

Regards
Sergio Masci
-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist