4 ms·
I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e. // do blah blah obvious_thing; obvious_thing; obvi
by nghst 13y ago
I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e.
// do blah blah
obvious_thing;
obvious_thing;
obvious_thing;
obvious_thing;
// do something else
obvious_thing;
obvious_thing;
obvious_thing;
obvious_thing;
Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later.
This is really useful in something like drawing code.
- wdewind 13y agoHere's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..
- jeremiep 13y agoIt should be pointed out that with inlining, both versions are exactly the same at runtime. Descriptive function names never lie, comments often do.
- masklinn 13y ago> Descriptive function names never lie Beg pardon[0]? function _utf8Encode(&$arr){ for($i=0;$i<(count($arr['parameters']));$i++){ $arr['parameters'][$i]= $arr['parameters'][$i]; } } function _utf8Decode(&$arr){ for($i=0;$i<count($arr['parameters']);$i++){ $arr['parameters'][$i]= $arr['parameters'][$i]; } } Or[1] public static string ReturnEmptyStringIfNullElseValue(string value) { if (value == null) { return ""; } else { return value.ToString().Trim(); } } [0] http://thedailywtf.com/Comments/There-and-Back-Again.aspx http://thedailywtf.com/Comments/There-and-Back-Again.aspx [1] http://thedailywtf.com/Articles/Common-Functions,-not-Common-Sense.aspx http://thedailywtf.com/Articles/Common-Functions,-not-Common...
- jeremiep 13y agoI stand corrected. Thank god I never have to deal with such code!
- wschroed 13y ago> Descriptive function names never lie, comments often do. Description function names lie just as much as comments. For example, I have run into cases in the wild where things like "get_item()" create database entries before returning a value. Yes, side effects are evil, etc etc, but the point is that at some point, somebody maintained the code and did not update every use of get_item() to now be get_and_or_create_items_if_it_is_sunday(). In rare cases, I have seen them at least update the local documentation.
- collyw 13y agoWhat's to say a function gets "fixed" without updating the name, in the same way that comments will not get updated? I see it would be less likely in a function, but not impossible.
- fournm 13y agoThis isn't always possible in every case--it's not too hard to imagine a lot of trivial assignment all going on at once, that isn't immediately obvious what it is or why on earth it exists. //really bad example, just something really repetitive function main() // set up month boundaries janStart = blah; janEnd = blah; // ... decStart = blah; decEnd = blah; end where it's not too hard to imagine many languages without great pointers needing to keep that inline to avoid making all of those variables global. In some (hopefully most) cases just better design in general can get around it, but I wouldn't always count it out immediately. edit: oops, formatting fail.
- zimbatm 13y agoAnd now you have three places to look at instead of one.
- wdewind 13y agoHow do you figure?