I'm a big fan of self documenting code, but I'm curious. What are your thoughts about the following statements from a blogger?If I see someone has written an event, I try to get rid of it – this goes 2x for custom events.If I’m working on someone’s production code and I see comments, I refactor and delete them.I rarely use conditionals.
•If I can identify way to clarify the code to make a given comment superfluous (and thus removable), I'll likely do so.•I tend to aggressively search for ways to minimize the use of conditionals in logic I'm writing.
Quote from: quadz•If I can identify way to clarify the code to make a given comment superfluous (and thus removable), I'll likely do so.•I tend to aggressively search for ways to minimize the use of conditionals in logic I'm writing.If the comment deciphers the code in human terms, I'd see "cleaning it up" as a waste of time
def handle_batch_image_result(rowid, local_path, box_size, params) ephemeral_catalog_id = params["cid"] local_result_dir = File.dirname(local_path) item_id = (ephemeral_catalog_id << 40) | rowid # pack catalog id and row id flags = ImageRequest::FLAG_THUMBNAIL result = [item_id, local_result_dir, flags, box_size] @window_svc.msg(:cache_result, result) end
def pack_catid_rowid(ephemeral_catalog_id, rowid) item_id = (ephemeral_catalog_id << 40) | rowid end def handle_batch_image_result(rowid, local_path, box_size, params) ephemeral_catalog_id = params["cid"] local_result_dir = File.dirname(local_path) item_id = pack_catid_rowid(ephemeral_catalog_id, rowid) flags = ImageRequest::FLAG_THUMBNAIL result = [item_id, local_result_dir, flags, box_size] @window_svc.msg(:cache_result, result) end
I'm not sure what you mean by the second thing, you mean less jumping between locations of instructions, whether you are using loops, gotos or conditionals?
while data_remaining if buffer_full flush_buffer end add_data_to_buffer end flush_buffer # make sure final data is written out
while data_remaining add_data_to_buffer if buffer_full || done flush_buffer end end
I suppose one could say, "oh, well, ideally someone should have kept the comments up to date!". But the practical reality is code is less likely to lie than comments. Thus, I'd rather see intent expressed in code rather than as comments wherever possible.
In C you usually only comment exceptional cases or work-arounds for some issue or other. My all-time favorite useless comment is "this is a hack". Shit yeah! Now explain why you had to do it dipshit. But the explanation is not forthcoming. Sigh.These are the kinds of comments that need to be removed. Along with the hack that made it necessary.