re: I love to document my code. Am I doing it wrong? VIEW POST


First of all, thanks for bringing this subject up, as it’s a very nice opportunity for all of us to learn with each other.

I’ve encountered a fair share of times when I needed to reuse some legacy functionality only to find out that it had so many long methods it would be better to rewrite or copy the code than mess with it and risk breaking it.

I think OO and agile principles are tools made to handle the assumption that the requisites will always change in the most unpredictable way, so breaking the code in small, coherent, reusable methods/ classes pays of most of the times, even if you can’t see it when you first write the code.

On the other hand, there’s no better time to refactor your code than when you’re writing it, with everything fresh in mind.

As for the comments itself, I think if you have to explain the code most probably you haven’t written it clear enough... You can extract hard coded numbers and strings to well named constants, “if” conditions to methods, and so much more.

That being said, of course there’s no silver bullet and it always depends on common sense.

code of conduct - report abuse