I believe you cannot over document your code. Other developers who may not know the framework may find it helpful in addition to framework documentation.


I’ve often heard that your code should explain itself. I also agree with this, but I also feel like we engineers like to make things harder on ourselves in an already extremely taxing career.

Realistically speaking, you may not always be on a team where everyone knows the framework and everyone is at the same skill level. Most likely you’ll have an assortment of: skill sets, skill level, framework experience and of course priority.

On larger teams you may have floating engineers who have their hands on multiple projects – increasing the difficulty level to jump in and out while being efficient. Add all of this up and you have a person who I’m sure wouldn’t mind having some clean text to spell things out.

Sure there is framework documentation, providing you’re not rolling completely custom, but if 3 extra lines in a controller explain a route or method and omit the developer from opening up another tab in their browser I see it well worth it.

That being said, I do believe messy documentation can confuse instead of clarify.

No Comments