[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