Hacker News Reader

Comment by shadowgovt | Hacker News Reader

To be honest, I see two positives regarding what Codemaker has provided here.

One is that (glancing through the comments) they're actually significantly more thorough than what is already there and they're at the level of thoroughness that a new user may actually want. Phil Webb is quite right; this is the level of detail someone new to the codebase could use, and if you could generate it dynamically on the fly as a "Help me understand what I'm looking at" tool that'd be really nice-to-have.

Second: I've definitely worked at places so tight-ass about code documentation that they do want "makeAppleRed(): Makes the apple red." Mostly because they're using doc engines that do a bad job of letting you know a function exists at all if it isn't documented. I have no doubt Codemaker is going to make its money on those places.

View on HN

> One is that (glancing through the comments) they're actually significantly more thorough than what is already there and they're at the level of thoroughness that a new user may actually want.

Consider this real example from the pull request:

  /**
  * Returns the plugin version property.
  * @return the plugin version property
  */
  @Input
  public Property<String> getPluginVersion() {
      return this.pluginVersion;

To me this seems less like a useful comment, and more like a joke trying to highlight the absurdity of aiming for complete javadoc coverage.

I agree on that example.

But contrast with this example: https://github.com/spring-projects/spring-boot/pull/39754/fi...

A function named `apply` with no documentation; you have to go up to the class to find the docs. And yes, it's not DRY to repeat the docs, but the fact the tool can pull relevant context into this location is helpful if it could be used as an on-the-fly doc generator (assuming, of course, it gives true output).

People (understandably) don't want to repeat themselves but they also can't predict what entrypoint a reader enters their class from. I've definitely bounced off APIs before because something like `apply` isn't doc'd even though it's doc'd in source twenty lines away (because I'm busy; I'm not scanning entire source files on the off chance that the thing I'm looking for is nearby).

Unfortunately, your brain will have been trained to ignore all comments by the 100 other completely useless comments that do nothing but add noise.

If the tool generated that one comment without generating any useless comments, then it might be worth using.

> /* > * Determines the GitHub tag for the given project. > * @param project the project for which to determine the GitHub tag > * @return the GitHub tag for the project > */ > private String determineGitHubTag(Project project) {

Here's a sample of the crap you get, for 3000+ files, multiple comments per file, all this inane, that anyone with two brain cells could figure out just by reading the name of the function. If the project didn't already have these sort of comments, then adding them now is a choice that the maintainer of standards would have to make, not some random contributor.

Do you have an example of those comments you think would be helpful for beginners?

The second point doesn't seem like a positive on the whole, except maybe for the company selling it, in the "there's good money to be made in being part of the problem" sense.

Edit: I noticed one comment that seemed like it added some useful context: For CheckAdditionalSpringConfigurationMetadata.Report::iterator it says "Each line represents a source code file and its associated problems." However, this turns out to be completely wrong, if I'm reading the code right, because a line could represent a filename, or a problem, or just be a blank line. The comment gives the appearance of being helpful while actually just adding confusion and wasting everyone's time.

> The second point doesn't seem like a positive on the whole, except maybe for the company selling it, in the "there's good money to be made in being part of the problem" sense.

No argument there (I don't miss those firm's doc standards). But you can make a lot of money being part of the problem in the business universe.

> The comment gives the appearance of being helpful while actually just adding confusion and wasting everyone's time.

That's definitely a concern; if the tool doesn't work it doesn't work, potential or no.

I think the first comment (https://github.com/spring-projects/spring-boot/pull/39754/fi...) looks helpful, although it is repeating info you can find in the class docs, the fact you have to go to the class docs to find it is an issue. A tool that could on--the-fly generate "Give me context for this function" (and give the right output) would be pretty useful for comprehending a codebase.

I don't know about that one. As you say, it's just repeating the class documentation, so maybe the tooling should make it easier to view the class docs if that's the problem. The generated version is also less clear: In what sense are the conventions "necessary"? The process "includes" the steps listed, but does it also include other things?

Reply on news.ycombinator.com