DEV Community

christine
christine

Posted on • Originally published at christine-seeman.com on

Code Documentation – before, after, and during coding

Sometimes you just need to started on some design for work on a larger ticket or new feature, you want to get your thoughts down and maybe start plotting out a code flow or some potential classes but what app do you reach for?

So much of the time I reach for Google Docs, for my personal or professional work. It’s easy, automatically backs up your work, and makes it very simple to share the document or convert it to another format. Opening a Google Doc, and starting to type out some pseudo code can be frustrating with the automatic capitalization or the code just not displaying as you would like. I have found the Code Blocks extension extremely awesome with that. Putting in code next to text is a breeze with it.

Helpful tip – If you are using Google Docs you can change up your preference to not annoyingly capitalize the first letter in a sentence (which is rather annoying for your Ruby classes which like to start with a non-capitalized letter).

Sometimes you just want to work on a spike story or share research that you had to done on a particularly hard debugging process or obscure part of your application. For this type of information, I like the use Confluence, a GitHub readme, or even the GitHub pull request itself. Just depending on if it is something I am currently fixing (it will go in the GitHub PR, preferably with screenshots if it a UI type fix), research for tickets or design coming up (Confluence, so easy to share and searchable for other developers) or if it is something that is needed for the code itself, like metadata or installation information, a readme works well. As a developer, I am trying to improve my git commits and PR for future development and maintenance. I highly ecourage anyone working in Git to check out Tekin Süleyman’s awesome “A Branch in Time” talk. Also his blog post on creating useful git history has some great Git tips and tricks, and really makes you think about how your git comments today, and effect someones code tomorrow.

For UML and flow diagrams, LucidChart, is my current app of choice. It is an online diagramming tool that has a lot of flexibility on what you want to show. Coming up with your flow diagram isn’t too hard, just make use of the typical shapes and lines. For me drawing the lines for the code that is calling a self.method was the hardest, but LucidChart has some pretty good tutorials that can walk you through the process, and help you with all the keyboard shortcuts that make you work life happier.

For the documentation of the code itself, I love writing code that is self documenting. For years with writing Java, if your code needed to have comments above it so other developers could understand what it was doing, it was probably too complicated. Writing comments were not encouraged, and refactoring out methods, and patterns to be better descriptors were the norm. Now with Ruby and the software I develop on, there are more comments in the code base. There doesn’t seem to be any stigma with code comments. Sharing information on how to use a command object, or the usage of an API or providing context on a classes public contract all seem to be valid use cases for inline code comments. I am getting used to using comments effectively in Ruby, and the not bring over any Java stigmas that I might have carried over about comments. I still do lean towards refactoring out code into smaller chunks with self descriptive method names, but do understand when code comments are helpful. All my method names tend to be more verbose, and I am still working on remembering to snake case everything.

There are so many different things that we have to document as developers that it is so important to figure out the best tools and applications that work for you. So, you as a developer, can document code effectively, efficiently and hopefully in a way that other people can find it and use it. Because the only thing worse than not documenting code, is not using code documentation.

Discussion (6)

Collapse
cjbrooks12 profile image
Casey Brooks

I recently ditched LucidChart for PlantUML. It is basically a programming language for creating all kinds of diagrams, and it is amazing how much easier it is to create diagrams as code rather than fighting a GUI.

Collapse
vinayhegde1990 profile image
Vinay Hegde

Another alternative to creating diagrams using code is MermaidJS

Not only it has a fully functional web-app one can use if one doesn't want to install anything but also it integrates with most code Editors such as Atom, VS code, Sublime etc. Happily using it for 3 months now :)

Collapse
cseeman profile image
christine Author

I'll try checking that out. There is a learning curve to LucidChart, and is a bit heavyweight for some diagrams.

Collapse
kiichi profile image
kiichi

As for paid version, Confluence + Draw.io + Visual Studio Online work pretty good. Just note that i'm pretty much using those doc & drawing tools for many years, here I'm just suggesting if developers can budget for those tools.

  1. Confluence - This is one of greatest documentation tool after I used wiki and google docs for my teams many years.
  2. Draw.io - I use Google docs a lot but as plugin of confluence, it really speeds up things. Just hit curly brace and type first a few chars "dr" then you can enter drawing mode in 2 seconds.
  3. Visual Studio Online - especially i like their PR screen which you can drag and drop screenshots, diff tools, inline comments, etc...
Collapse
tux0r profile image
tux0r

Generally spoken, your code should be easy to understand even without any comment. But if you ever find yourself having to maintain your own code from last year, you'll love extensive "what have I done here and why?" prose texts in your code. :-)

Collapse
cseeman profile image
christine Author

I've seen that done in a few comments, but it isn't something that I have tried yet. I'll have to look more into that!