4 ms·

I hate these "languages implemented in comments" jsdoc is another one. They force you to write more comment code (sometimes the comment will be longer than the

by dusted 5y ago

I hate these "languages implemented in comments" jsdoc is another one. They force you to write more comment code (sometimes the comment will be longer than the actual function), they force you to repeat yourself, but with ever so slightly more information and different syntax (but this time, forget about syntax checking or highlighting!). They disconnect actual code from the documentation, even if they're "right there next to it" it's annoying to have to edit two different places, and possible to forget to update the comment. I'd probably accept one that scrapes comments, but has no syntax, except maybe something _VERY_ short to enable/disable the scraping of an individual comment. I'd prefer it if the language allowed me to write this metadata directly into the syntax, so that it is natural flow to include the explanations where they are needed. One thing I found interesting and nice about Objective-C syntax was the way function declarations made them self-explanatory. You never needed think twice about what the parameter was for (assuming the function author did a slight effort in naming). (int) Multiply: (int)x with: (int)y result = Multiply: 23 with 3; (int) Subtract: (int)a from: (int)b andMultiplyBy: (int)c result = Subtract: 1 from: 4 and MultiplyBy: 2;

pydry 5y ago
I dislike them too. Not only because it's an inducement to duplicate everything, but because the documentation usually loses important context that * Helps you locate it by knowing what you want to do but without e.g. knowing key words. * Lets you know which APIs to use it with. * Lets you know how to chose between sounding seeming APIs. All of this context can be added but then you add it everywhere and suddenly your comments are ballooning in size and you're duplicating the same context multiple times across multiple methods.
- tpoacher 5y ago
  Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One thing I like about python is that the documentation for any function or class is actually part of the object (held in its __doc__ attribute), and the whole 'triple-quoted string above the function' convention is actually just syntactic sugar, which assigns that string to the object's __doc__ attribute. The beauty of this is that you can completely externalise documentation into another package, if you really wanted to, and attach it to your objects separately! This means you can keep documentation separate, keeping your code as free of comments as you like. One nice thing about this, is that it allows you to maintain two 'categories' of documentation: the user-oriented documentation goes into the external file, whereas any 'developer-oriented' documentation which is explicitly for the maintainer's benefit while looking at the code, can appear directly in the source, and you can be sure that this will be safely removed from the user-oriented documentation later.

by dusted 5y ago

pydry 5y ago

I dislike them too. Not only because it's an inducement to duplicate everything, but because the documentation usually loses important context that * Helps you locate it by knowing what you want to do but without e.g. knowing key words. * Lets you know which APIs to use it with. * Lets you know how to chose between sounding seeming APIs. All of this context can be added but then you add it everywhere and suddenly your comments are ballooning in size and you're duplicating the same context multiple times across multiple methods.

tpoacher 5y ago
Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One thing I like about python is that the documentation for any function or class is actually part of the object (held in its __doc__ attribute), and the whole 'triple-quoted string above the function' convention is actually just syntactic sugar, which assigns that string to the object's __doc__ attribute. The beauty of this is that you can completely externalise documentation into another package, if you really wanted to, and attach it to your objects separately! This means you can keep documentation separate, keeping your code as free of comments as you like. One nice thing about this, is that it allows you to maintain two 'categories' of documentation: the user-oriented documentation goes into the external file, whereas any 'developer-oriented' documentation which is explicitly for the maintainer's benefit while looking at the code, can appear directly in the source, and you can be sure that this will be safely removed from the user-oriented documentation later.