6 ms·

On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows c

On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows context explanation in a very streamlined and human way. The author mentions for preconditions to just “read the code”. I consider this bad advice. If using an external library, would you rather hover over the method and see its conditions, or would you rather crawl into the third party source code? I recommend that you treat the internal structures of your code as reusable third party libraries, and not assume that anyone will be familiar with it or how it’s used. Often my JSDoc comments take up more vertical space than the code itself, sometimes even with ASCII tables or example usage code. I believe this is one of the best approaches to documentation, especially paired with a automated documentation site generator tool. Code is read much more than it is written. You need to think like a writer and consider your audience.

teknopaul 5y ago
nothing wrong with the tool, the issue is with the comments that exist and those that don't. getFoo() does not need a comment. if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format. if getFoo() does need a comment, consider changing the code so it doesn't. Code is read much more often than its written: so be concise. If the docs can be automated by a simple tool, by definition, they were not necessary.
- nomel 5y ago
  I generally enjoy a brief description of the overlying concept, at the top of each function. I don't care to know how a function is implemented as much as rough details to help me navigate the new/forgotten code space/context. Usually, a quick example of usage, within some relevant context, is enough to push me in the right direction. If I have to read every line of implementation to know wtf is going on, then I'm probably going to have a bad time.
- iudqnolq 5y ago
  Depending on the context, I might mention if getFoo is expansive, is cached, talks to the network, or can throw.
alerighi 5y ago
If the name of the function and the parameters are clear, documenting the code seems useless. Take this real example: /** * change the temperature set point in use by the thermostat * * @param ctx the thermostat context * @param sp the new set point in 0.1 celsius degrees * @return 0 on success, < 0 in case of an error */ int change_sp(void *ctx, int sp); But we can change around the name of the parameters like this and use proper strict types: /** * change the temperature set point in use by the thermostat * * @param thermostat_ctx the thermostat context * @param set_point the new set point * @return SUCCESS on success, otherwise an error code */ error_t update_temperature_set_point(thermostat_ctx_t *thermostat_ctx, celsius_degree_t set_point); And thus the doc comment now it's useless and can be removed, leaving only: thermostat_error_t update_temperature_set_point(thermostat_ctx_t \*thermostat_ctx, celsius_degree_t set_point); And in a codebase, more than 95% of the comments would be like that. There are the exception where you need to explain something in more details. In that case you first should ask yourself if there is really not a better way, and if not in that case the doc comment is fine. In all the other cases, it's probably not. Doc comments on the other hand really makes the code less readable, the increase the number of lines for most of the times not saying anything useful at all.
- moeris 5y ago
  That's more of an argument for them being overused, not for them being useless.
  - squiggleblaz 5y ago
    It's an argument for a certain code style, characterised by descriptive names and specific types. This calls for a language capable of e.g. doing maths with user-defined types, which not all languages can do. I think one of the major motivators for the original style of code are legacy pressures and a concern about code width. If every other function that manipulates temperature set points takes "int sp", then you're going to get a lot of pressure for consistency. A lot of programmers regard consistency as a goal in and of itself, and it's very easy to demand it during a code review. However, the demand for consistency prevents us from finding a new consistent target without excessive amounts of work. It may be better to reach a new consistency within a narrower scope, as long as a consensus has been reached to extended that consistency outwards. In this system, consistency should be viewed as a compromisable target: something that makes you ask a careful question. And when asking a question, take into consideration the propensity of the code author to view a question as a demand. If you're a senior and the code author is a junior, presume that means: ask a genuine question vocally; write down minutes of your discussion. The code width concern is a bit silly, but for some reason we assume that things get weird when lines exceed 80 characters. That's easy to do.
lucideer 5y ago
JSDoc !== Javadoc The reason I say that is because the language features (or lack thereof) are a big contributor to the need for JSDoc/Javadoc. i.e. JSDoc adds much more to Javascript than Javadoc adds to Java. For example, there is much less need for JSDoc in a Typescript project.

teknopaul 5y ago

nothing wrong with the tool, the issue is with the comments that exist and those that don't. getFoo() does not need a comment. if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format. if getFoo() does need a comment, consider changing the code so it doesn't. Code is read much more often than its written: so be concise. If the docs can be automated by a simple tool, by definition, they were not necessary.

nomel 5y ago
I generally enjoy a brief description of the overlying concept, at the top of each function. I don't care to know how a function is implemented as much as rough details to help me navigate the new/forgotten code space/context. Usually, a quick example of usage, within some relevant context, is enough to push me in the right direction. If I have to read every line of implementation to know wtf is going on, then I'm probably going to have a bad time.
iudqnolq 5y ago
Depending on the context, I might mention if getFoo is expansive, is cached, talks to the network, or can throw.

alerighi 5y ago

If the name of the function and the parameters are clear, documenting the code seems useless. Take this real example: /** * change the temperature set point in use by the thermostat * * @param ctx the thermostat context * @param sp the new set point in 0.1 celsius degrees * @return 0 on success, < 0 in case of an error */ int change_sp(void *ctx, int sp); But we can change around the name of the parameters like this and use proper strict types: /** * change the temperature set point in use by the thermostat * * @param thermostat_ctx the thermostat context * @param set_point the new set point * @return SUCCESS on success, otherwise an error code */ error_t update_temperature_set_point(thermostat_ctx_t *thermostat_ctx, celsius_degree_t set_point); And thus the doc comment now it's useless and can be removed, leaving only: thermostat_error_t update_temperature_set_point(thermostat_ctx_t \*thermostat_ctx, celsius_degree_t set_point); And in a codebase, more than 95% of the comments would be like that. There are the exception where you need to explain something in more details. In that case you first should ask yourself if there is really not a better way, and if not in that case the doc comment is fine. In all the other cases, it's probably not. Doc comments on the other hand really makes the code less readable, the increase the number of lines for most of the times not saying anything useful at all.

moeris 5y ago
That's more of an argument for them being overused, not for them being useless.
- squiggleblaz 5y ago
  It's an argument for a certain code style, characterised by descriptive names and specific types. This calls for a language capable of e.g. doing maths with user-defined types, which not all languages can do. I think one of the major motivators for the original style of code are legacy pressures and a concern about code width. If every other function that manipulates temperature set points takes "int sp", then you're going to get a lot of pressure for consistency. A lot of programmers regard consistency as a goal in and of itself, and it's very easy to demand it during a code review. However, the demand for consistency prevents us from finding a new consistent target without excessive amounts of work. It may be better to reach a new consistency within a narrower scope, as long as a consensus has been reached to extended that consistency outwards. In this system, consistency should be viewed as a compromisable target: something that makes you ask a careful question. And when asking a question, take into consideration the propensity of the code author to view a question as a demand. If you're a senior and the code author is a junior, presume that means: ask a genuine question vocally; write down minutes of your discussion. The code width concern is a bit silly, but for some reason we assume that things get weird when lines exceed 80 characters. That's easy to do.

lucideer 5y ago

JSDoc !== Javadoc The reason I say that is because the language features (or lack thereof) are a big contributor to the need for JSDoc/Javadoc. i.e. JSDoc adds much more to Javascript than Javadoc adds to Java. For example, there is much less need for JSDoc in a Typescript project.