About code readability (for fun)

[Processor-Dev1l]

My first language was C. When I started learning it I used only
notepad and compiler.
Tabs were really important for the code readability and some comments
made the code also more readable.
But some ppl didn't like it so first IDE editors were created to
highlight parts of the code.
c# went even far and also created so called regions for even better
readability.

Why am I writing this?
Well, I just sent my code for review to my current client and I got it
back with words: "It is not commented enough".
They want me to comment every stupid line of the code (even xml
comments), so it should look like this:
/// <summary> //start of xml comment
/// something to work with //content of xml comment
/// </summary> //end of xml comment
/// <param name="someData"></param> //parameter name of xml comment
public static int someFunction(int someData) //declaration of method
someFunction
{ //start of someFunction method
return int someData*10; //returning product of someData variable
value and 10
} //end of someFunction method

My question is: IS THIS READABLE??? I THINK NOT!!!

[Jamie Fraser]

Maybe they don't want it for readability, but if they are treating your code as "sealed" (i.e. an external API) then the comments are very useful, as they appear integrated within Visual Studio intellisense.

[Peter Smith]

On Wed, Nov 25, 2009 at 4:13 AM, Processor-Dev1l <process...@gmail.com> wrote:
>> ...

>>                public static int someFunction(int someData) //declaration of method
someFunction
>>

Far too undercommented. I'd send back.

               p/* The English letter 'p' */u/* The English letter 'u' */b/* The English letter 'b' */l/* The English letter 'l' */i/* The English letter 'i' */c/* The English letter 'c' */....

[Benj Nunez]

Putting comments in code are ok as long as it's done in moderation:
Too little comment(s),
fellow developers/managers would ask/clarify what your code does. Too
much comment(s)
would get in the way in reading the source code. :)

More often than not, if the code has been written to be descriptive
enough, then
there is no need to put comments (self-documenting).

More on this here: http://www.devtopics.com/13-tips-to-comment-your-code/


Cheers!



Benj

[Cerebrus]

Okay, I thought I replied to this during worktime but must have lost
it somewhere in the numerous windows I have open.

You haven't really shown us what your code looked like when you sent
it for code review. "It is not commented enough" does not necessarily
mean that every line should be commented, but it does mean that the
reviewer found atleast a few lines of code where the developer's
*intent* was not readily apparent. Maybe you should clarify with them
before assuming that they want you "to comment every stupid line of
the code". If their expectations are indeed as you fear, it would
indeed be the first instance I've ever heard of where XML comments are
commented upon ! Maybe then you should ask them if they need comments
on the comments to the XML comments... ad infinitum ;-)

As Jamie mentioned, XML comments are a highly useful tool especially
when generating API's or documenting public interfaces.