[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

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
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":


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?

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