Useful comments
-
The policy at where I work is clear: thou shalt comment your code.
The legendary CEO who wrote much of the software we have to fix right now, went to another continent, where he keeps designing websites in photoshop.
The company has a framework called, let's say, Dynamic Objects (not really, but this is the only thing I changed in the sample). And this is what his comments look like:
/**
* Container for appControler object (dynamicobjects)
*/
var $appControler;
/**
* url to include to show the view
*/
var $view_url;
/**
* Container for context from the dynamicobjects system
*/
var $context;
/**
* Container for screen from the dynamicobjects system
*/
var $screen;
/**
* Container for unitOfWork from the dynamicobjects system
*/
var $unitOfWork;
/**
* Container for the request used by the dynamicobjects system
*/
var $request;
/**
* Container for the command comming from the AppControler of the Dynamicobjects system
*/
var $command;That's how it goes for some 20 other variables. You'll notice the comments follow a clear pattern. Also, the variables have consistent names, either they're camelCased, either under_scored. Tertium non datur.
I'm thinking about changing the comments to something more relevant, like:
/**
* The following variable's name is appController
*/
var $appControler;
/**
* The following variable's name is view_url
*/
var $view_url;
/**
* The following variable's name is context
*/
var $context;
/**
* The following variable's name is screen
*/
var $screen;
/**
* The following variable's name is unitOfWork
*/
var $unitOfWork;
/**
* The following variable's name is request
*/
var $request;
/**
* The following variable's name is command
*/
var $command;
-
What is this language?
Looks like the bastard child of PHP and javascript.
-
It's php with phpdoc (javadoc for php) comments. Ironically, they pass off on the most valuable thing you can do with phpdoc, which is hinting the type of the variable. A decent (read: only Zend) IDE is then able to pick it up and do codesense everywhere you use the vars.
-
This is why I tend to comment too little, rather than too much. Commenters like these should be shot and hung and tossed into the next river (in this order).
I *do* understand that comments may help a lot, but they have the general tendency to be out-of-date and misleading as soon as someone finishes typing them.
(this fact is a corollary of my other principle: Software turns into legacy software after leaving the compiler)
-
It actually looks like the new addition to C# in Framework 3.0. Its called local type inference. It basically means that it will bind it together when it is assigned. It takes the type of the assigned object. It could be pretty useful in factory patterns and code generation.
see here http://msdn2.microsoft.com/en-us/vcsharp/bb417257.aspx
-
about my post about local type inference... The code wouldn't compile anyway because it needs to be assigned at the time it was declared if you use the var keyword in C#.
-
It's php 4, I thought it was obvious :) It's part of a class, but i wanted to post only what's necessary.
Oh, and before someone says "the real WTF is.." There's enough wtfs in this to fill a dozen of threads. I created an account only in order to be able to share my pain in the threads here :)
