DEV Community

Discussion on: Don't document your code. Code your documentation.

Collapse
 
robertmjohnson profile image
Robert Johnson

A problem with depending on your function names for documentation is that it makes your code rather verbose. (Anyone who has been a Java for dev for any length of time knows exactly what I'm talking about!) Following the logic of Clean Code, I suppose that map should have been named applyFunctionToAllElements or something. Fortunately though that isn't the case, and after reading the documentation you can remember what map means and be spared all that verbosity.

I'm not against favoring code over comments though. If it's a private method that has a very specific purpose and isn't called from many places then I'm happy to not give it a comment header. As ever, "it depends".

Collapse
 
scalawilliam profile image
William Narmontas • Edited

Whenever I found naming hard, I realised had an incomplete idea of the domain and goal.

Why am I mapping this, why am I transforming this?