I originally wrote this as a response to @nonlinearnygma's post:
Article No Longer Available
It got really long and I f...
For further actions, you may consider blocking this person and/or reporting abuse
I really like your approach to documentation. I have to disagree on one point though: comment-generated docs. Generally I think that comments in code are a big no-go. I've never come across a case where good naming and clean code can't replace them.
Don't get me wrong, on projects others have to use I highly value good guides - but method-by-method explanations are either necessary in case of "dirty" code, or unnecessary in case of clean code.
That's my opinion. :)
I know a lot of people agree with you on the comments too. :) I think comments in the code that repeat the code can be a burden to maintain, but I like to basically have a comment for each public function or type/object that briefly explains what you would use it for. Or to describe any non-standard code or design.
In my experience I have never come across a case where a comment was necessary. Feel free to give me an example. I like to challenge this thought. There's one exception that I can imagine, that is "unclean" code, that is necessary for performance purposes. But other than that...? Open for a challenge! ;)
I've had the same opinion for a very long time, until I started paying attention to some places where a simple javadoc saves a good amount of unecessary research. Taking 2 quick examples that come to my mind:
Wildfly Swarm, an application server meant for micro-services, in it's prior implementation where you had to create a class to configure your server, had a "swarm.createDefaultDeployment()" method. It is a method that makes absolute sense if you consider that it does exactly that, but... what is a default deployment? What would be this method's name if I explained it's details using it's name?
Jsoup, a library to parse HTML in java, has a method that returns you an element's index considering the element list it's part of. Considering the domain it belongs, the method "elementSiblingIndex()" makes sense on it's own, especially if you're familiar with the terminology used in html handling, but again, how self-explanatory could/should be without getting a paragraph?
I'm always against any kind of extreme measures, which goes for both "no docs in methods" or "document every public method you have". Documentation is meant to make everything clearer and help other developers, and I think that the "Clean code doesn't need docs" idea, although great on it's own, ends up leading to confusing code that, even though made sense when it was created, now leads to "what is a default deployment after all?" kind of question.
And yes, I always love debating this, so let's go haha
I just want to clarify upfront: I didn't say no docs are necessary. I just said that method-by-method docs are unnecessary, if the naming and code is done well.
Here's my attempt to "fix" the above issues:
If you have any issues with these solutions I'd be happy to be challenged with those. :)
Indeed, and I agree that method-by-method documentation is makes as much sense as no documentation (I know that searchUserByName searches a user by its name ffs..)
Considering the examples, your solution to the second case is great, can't argue there, but when it comes to the deployment scenario, things get ugly.
Your ideas there lead to a spaghetti code structure that I've seen multiple times and is mainly what led me to question the statement "Clean code makes method-docs unecessary".
Think about what's involved in a deployment and the amount of tweaks you can do. Now let's consider the defaultDeployment option. I'm not saying you CAN'T do exactly what you said, but how many proxy methods with 1-2 lines would you need to create in order to "keep it clean"? And how much better would your code actually be after that? Would that amount of code and methods do a better job for your project than, say, a comment that explains what a single method does? Also, is your increased interface usability actually going to be of any use? Maybe your 3 new methods, all with a very clear signature, are never going to be used again (just like tons of generic code out there). And I say that based on multiple projects I've seen and worked, with exactly that kind of structure, where a proxy method was created for clarification, but 2 weeks later a new method was created, proxying the former, and eventually you end up with a 10 method chain, with 8 of them having less than 3 lines on them, and that's where I ask myself "is this really better than a 1-2 lines doc on a single method with, say, 3 parameters?". So far, my answer is no.
Considering my last 3 months of work (brand new project, from scratch), I've written very few method docs, but when I consider the amount of proxy methods I'd have to create in order to clarify what my 20-30 words doc does (including some parameter options), I can't see how that would be better.
Summing it up, I think that renaming your methods should always be considered ("are the methods name clear on their intentions" was actually one of our PR checklist items), but shouldn't be used as an argument to completely avoid method-specific docs, especially considering complex domain-specific scenarios.
Also wanna mention that indeed, you never actually said "Nobody should document their methods, ever", but your statement on "In my experience I have never come across a case where a comment was necessary." tends to lead less experienced developers to go full no code-docs, and that shouldn't be a thing (trust me, it has happened before with "Clean Code" book).
One of the most poor documentation i've ever seen is: sailsjs docs.
I really enjoy your post and it's really what i think about a documentation.The example/Guide is for me the part that the project doc team might focus on.
It must be like Explain like i'm five tag here
Also the "Sometimes people leave out explaining where the project might not be the best fit, but it is very useful and appreciated by users." Is a really good idea
I agree the examples should be explained very simply. There's always going to be somebody that finds a detailed explanation helpful, even if other people skip over it.
I think the problem is that devs write docs the way they understand it. It's like giving someone giving you their class notes, but they write in short-hand or in analogies you don't exactly understand.
I absolutely appreciate the tag #explainlikeimfive--because, personally, need things to be explained in the most basic, layman terms as possible.
Sometimes people don't want to debase themselves to that of a child, mostly due to pride (and selfishness).
There are some designers (like me) who want to understand how to code better so that we can collaborate with engineers to streamline building a functional and new user-friendly product.
I have yet to find a #nicedoc. :(
Thank you for writing this post! It was a great read!
Totally! Thanks for pointing that out. Writing documentation requires a shift in perspective and some detachment from the internal implementation of the code. Even the documentation links I included I think all suffer from this issue.
I wish developers would be more open to inviting other people into the documentation process. The best documentation can only be written by involving people that don't have an intimate familiarity with the codebase. Ideally the terminology used in the code itself reflects the way users actually talk about the concepts involved.
I hope you find a #nicedoc some day!
You just gave me a brilliant idea. Brb brainstorming.
Excited to see what you come up with :)
Absolutely wonderful post Eli 👏👏👏
Thanks! I've been a big fan of this website and community for a while and I've been meaning to start contributing.
I often find myself unsure "where to start explaining from?".
People who come to read your document have diffent technical background, I never got confident I wrote documemt they all can find information they wanted to acknowledge.
Yeah, it can be difficult to find where to start. I think examples and guides is usually a good place to start. If you or one other person has a question (even if it feels like a silly question) or isn't sure how to do something, you can basically guarantee that somebody else has the same question. Something is better than nothing, even if it's just adding a brief note.
At the beginning of a guide you can say where you expect them to already know, and what the guide will show them from there. That way people know if it's relevant to them before they read the whole thing.
I do feel at times that the Oracle docs expect you to already know the answer to the question, which is frustrating.
That is so annoying. To me that's usually a sign that they're a little out of touch with their users.
Docker docs are to die for
Those are some #nicedocs. Thanks, I added it to the list!
In my opinion, one of the main problems of documentation is how fast it gets outdated. In the past I tried things like Specification by example and "Living documentation" but it tends to be too expensive (time and money) to be effectively used in real projects.
Right now, we're using Guru as our documentation platform. It keeps the documentation small (very important to prevent it from getting old pretty quick) and reminds authors to check their articles every now and them to see if they are up to date. I recommend to give it a try. We're pretty happy with this solution.
Thanks for sharing your experience! I've in the past tried the Literate Programming technique, but also found it very difficult to maintain.
Guru seems like a really interesting way of doing it; I'll check it out. My first impression is that it seems like it focuses on the experience of writing and using the documentation, which I like.
good job bro! it's really helpful post for all readers
if you really wanna see crappy documentation - feel free to implement dynamic yield :-)
in terms of good documentation, i think amazon web services are currently state of the art.
Thanks for the contribution, I added it to the list! AWS is a really great example of how it's hard to have too much documentation. Especially if they are organized as well as the AWS docs are. And now I know to stay away from dynamic yield :)
I'm glad it helped :) I didn't expect it to be such a popular topic; I'm glad you brought it up for discussion! It's been so cool seeing different people's perspectives on it.
I love how this is written in the perspective of writing documentation as a user instead of a maintainer or regular contributor!