DEV Community

Discussion on: Crates I Have Known And Loved

Collapse
 
deciduously profile image
Ben Lovy • Edited

StructOpt will use the doc comments above each field.

/// Activate debug mode
    #[structopt(short = "d", long = "debug")]
    debug: bool,

This snippet will include the string "Activate debug mode" in the help() method of your clap argument, so it is separate from the structopt annotation. I actually like this method because it encourages you to build the habit of using docstrings elsewhere too in general - with just "clap" you need to define the docstring using a separate syntax. I like keeping it consistent.

Is that what you were getting at?

Collapse
 
bhaibel profile image
Betsy Haibel

Yeah! That makes sense. I see what you like about it, and I agree that getting folks in the habit of using docstrings is is a good idea. I'm worried, though, about how non-obvious that API is. In a lot of ways, it turns that docstring into CODE, not "just" documentation. When I read your example at first, I didn't understand what was going on, because I'm used to the idea that code is code and comments are comments. Now that I know that, I'm fine, but... what about on a team project?

On team projects, there's usually a lot of "copy, paste, modify" going on. It's easy to dismiss this as laziness, but, really, it's just very human. Folks want to build features "efficiently" (in a way that minimizes time & effort) and in a way that none of their teammates will think is weird. Copying and pasting existing code is a great way to achieve both of those goals. Since other folks will copy/paste/modify our code, it's important to write code that can be copied and pasted! Sandi Metz calls this "exemplary" code -- code that's a good example for others.

So, now I'm putting myself in the mindset of someone who hasn't really used StructOpt before, and who needs to do something new with it. When I go to copy-and-paste this example code, I don't bother copying and pasting the docstrings -- after all, they're "just" comments. I'm supposed to discard them when I copypasta, right? But this results in code that's functionally different, too.

This is the kind of issue that code review is supposed to catch, but.... there's nothing "actively" wrong about the copypastaed section. It's missing something, but there aren't any bugs per se. The ways that it's not-quite-right wouldn't be obvious in a code review tool, so I give it a 50-50 chance of passing code review. And so now, we have a bad, undocumented example in the codebase that people will copy-paste from in turn.....

I do like the conciseness. Reusing docstrings is a clever anti-duplication mechanism. But it seems awfully fragile against "humans" to me!

Thread Thread
 
deciduously profile image
Ben Lovy • Edited

Ah, okay, I get what you're saying now. And you're absolutely right - the onus is on the user to ensure you're properly documenting your code, and there is a bit of "magic" there. That said, I find Rust's docstrings pretty dang magical already so that third slash suggests to me this comment is "extra special" somehow, even if it's not how a normal doc comment is used.

I don't have the perspective of having worked on a team before, but I'm surprised to hear that you specifically omit the docstrings - that's not something I usually do when I'm copying code I didn't write specifically because I want to be sure I have all the information I need as I build on it. For this library, anyone would simply have to know that they're part of the code.

You do have the option to skip the docstrings, though, and define your help strings directly using the about attribute:

    #[structopt(short = "d", long = "debug", about = "Activate debug mode")]
    debug: bool,

I think this circumvents the problem you're describing, but as before it's still up to your review process to ensure each field has this attribute defined.

I'd never understood why this would be preferable until now - thanks for the perspective!