[thelist] coding standards (comments)

VOLKAN ÖZÇELİK volkan.ozcelik at gmail.com
Sun Dec 10 01:18:51 CST 2006


If this discussion continues we can easily publish an evolt booklet on
standards :)
Not a bad idea huh?

While we're on coding and markup standards;

I just want to ask this inevitable question:
"Who really needs fully commented code?"

imho most of the time method names are self-documenting and
self-explanatory.

Well, documentation is a life saver when done properly;
but it is a real time waster if done improperly.
I will long to write fully commented applications if only I have thrice the
time
I have assigned to the project initially. But real life is different than
our utopic world.

Two examples to demonstrate what I consider "right" and "wrong":

wrong:

namespace com.sarmal.data
  public interface IQuery
{
/// <summary>
///     This method inserts to the table named "table"
///     and returns the unique identifier as an object.
/// </summary>
/// <param name="table" type="string">
///     <para>
///         The table to insert.
///     </para>
/// </param>
/// <returns>
///     An object value...
/// </returns>
object Insert(string table);


So f*ing What !!? The method is self explanatory itself and we ( actually I
)
have ammended 12 lines of unneccessary comment to it.

...

And and example to (imho) a good comment (from the same app):

/// <summary>
///    Converts string value (which is assumed to be encoded in
///    EnvironmentVariable.ResponseEncoding) to
///    a string with EnvironmentVariable.ServerEncoding,
///    escaping special elements (like single quotes) as well
///    to prevent security vulnerabilities (like SQL injection)
/// </summary>
public static string ToDBString(string value)
{
    return Converter.ToServer(Converter._ToDBString(value));
}


Any ideas?


Cheers,
-- 
Volkan Ozcelik
+>Yep! I'm blogging! : http://www.volkanozcelik.com/cre8/blog/
+> Going solo in Turkish: http://www.volkanozcelik.com/donkisot/
+> My projects/studies/trials/errors : http://www.sarmal.com/
+> Sardalya JavaScript Library: http://www.sarmal.com/sardalya/



More information about the thelist mailing list