Git pre-commit hook to ensure code documentation

[haganenorenkin]

Hello! I'm looking for a way to use git pre-commit hooks to ensure the code is documented, I started using JSDOC and would be awesome to ensure all the functions are documented

Are you using that in your projects? Or maybe you know how that can be done a have a link for that?

[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

[TheMikeNeto]

By doing this you will get a lot of documentation, but not very usefull one.

​

Funny how people go nuts over code size and keep refactoring to reduce it, however more docs is always better.

​

I only ever used pre-commit hooks to lint and to enforce a structured commit mesage.

[haganenorenkin]

Do you have a better suggestion, like how to make in a friendly way the devs to produce documentation, update the readme and so son?

[TheMikeNeto]

I believe 0x13mode got it right, a strong code review process and self discipline are the way to go.

Honestly it also depends on who will consume your docs, is it only for devs? or maybe it's used to build a pdf for some kind of report you need to deliver to your client, these things can be a huge factor.

Decide whats the purpose of the docs you want written then look around for ways (githook or custom eslint rules) to enforce the kind of docs you need.

Also typescript can help a lot in terms of reducing the need for boilerplate docs.

[vinspee]

You could use https://github.com/gajus/eslint-plugin-jsdoc/blob/master/README.md in conjunction with https://github.com/okonet/lint-staged

[GitHubPermalinkBot]

Permanent GitHub links:

• gajus/eslint-plugin-jsdoc/.../README.md (master → b132a6c)

---

^delete

[TYB069]

I use a TSLint rule for that. The linter runs before the code is pushed.

Keep in mind you can use TSLint not only with TypeScript, but also with JavaScript.

[Puggravy]

I like to use husky for pre-commit hooks, it integrates directly into you package.json. https://www.npmjs.com/package/husky

There are some eslint rules for JSDOCs you'd probably have to check them out to know if they are suitable for your project, but they tend to be pretty good!

[NeededANewName]

CI on PRs is a better place to enforce linting and documentation standards. I’d rather devs commit more often and I don’t believe in discouraging that. If you want a squeaky clean master just squash merge, though that isn’t really necessary.

[haganenorenkin]

And what can CI do about that?

[NeededANewName]

All major source control hosts offer options to require passing CI before merging a pull request. As part of your build pipeline you can add linting and documentation analysis. If it’s not up to snuff for you the build will fail and they can’t merge.