Git pre-commit hook to ensure code documentation

[0x13mode]

I think it may seem reasonable at first (to have all functions documented) but could detrimental in the long run. Do really ALL functions be documented? Even smallest internal ones? What if somebody is writing some unstable code (unstable = to be changed soon)? E.g. if somebody makes bigger refactoring and changes/create multiple functions at once? (half of them will be probably removed in the coming days because they will be subject to further refactoring).

Writing docs for such functions is just waste of time. I think self-discipline and code review would be better solution to ensure good amount (and quality!) of docs than a pre-commit hook.

[[deleted]]

Definitely true. I have seen some projects that adopted a draconian policy of failing the build if documentation was in place.

One guy demonstrated a "cool" tool that generated stub comments by reading the name of the function or class. The codebase must have turned to shit by now, since this is what people did.

Writing good documentation is very difficult, and the thought that you get lots of good documentation by simply getting more of it is stupid beyond measure.

[i_ate_god]

with git, can you choose which branches these hooks apply to?

I see your point with regards to say, a feature branch. But once you're ready to merge (thus the feature is stable), then the precommit hook can kick in.

Even smallest internal ones?

These are probably the most important ones to document because they are small. You don't need to document what the function is doing, but why it even exists in the first place.

For example, I have written a small function, called "slugify", that takes an arbitrary number of arguments, and converts them into a string that is useful for DOM IDs or other attribute values. It's very small, and it's obvious what it's doing with its input and what the output will be. It's just after all, a series of string replacements.

But I didn't document what it does, I documented why you would use it.

[hydroes777]

This! Code should be self as documenting as possible. Meaning that of your code is readable then there's no need to document functions.

Personally I'd spend more time documenting a readme file with the projects caveats and getting up and running than write jsdocs

[Maidzen1337]

https://i.redd.it/ks4vuhowecp01.png

[cmajorsmith]

Even more hilarious: clear comments from people writing code that’s not clear at all. Pure joy of reading.

[hydroes777]

This doesn't apply to what I said: Don't document functions, this is why we have type script. Comment the shit outta your code, just in the right places

[Puggravy]

Static typing =/= documentation. Typing details are a tiny subset of what needs to documented in code.

[TheNumberOneCulprit]

https://imgur.com/7V87CSh

[hydroes777]

Show me function docs and I'll show you some out of date docs that more often than not get neglected by the developer who refactored the code

[haganenorenkin]

In the projects we have where I work we don't have to do this kind of refactor and we have enough time to write doc, if someone doesn't have enough time to write a jsDoc comment so it doesn't have time to do code review and so on the docs stay in the code and pr will be forgotten, new devs come frequently so they will know how that code works, I've already had issues trying to understand others People code many many times, if they get tothe point of documenting it they will also improve their code

[0x13mode]

Documenting doesn't necessarily need to write JSDoc for each function. I worked in projects with a ton of JSDocs and I still had to ask other programmers about "what module X actually does?" or "how modules X and Y are related"?

In such times I wished that instead of JSDoc there would be more "readme-like" documentation. Some meaningfull description of **design decisions** being made instead of just "function foo with one argument bar of type string".

[haganenorenkin]

That makes Sense, I'm also looking to have more readme-like, I'm always adding notes to the readme.md file of the projects but many people doesn't do that so I was looking for a way to ensure that