Ask HN: Automatic generation of code documentation

by botbot on 7/13/2015, 1:29:31 AM with 4 comments
Hi HN,

I am a religious follower of DRY (Don't repeat yourself).

In my line of work, I tend to use modelling tools (eg. UML) in order to plan out and structure my code. Once the modelling has been done, I create, test and implement the program (with comments). Once the program is in place for its intended purpose, I document the code to the end-user.

My question is about automatic generation of code and/or documentation. It seems to me that whichever task in my workflow I choose, it is a 1 way mapping.

ie. Model -> Code

Code -> Model

Code -> Documentation

Documentation -> Code

So if I change my code, I then have to update my model as well as my end-user documentation.

There are ways I can automate model generation, but I am generally at the whims of the modelling environment when it comes to model regeneration from code. As well as this, generating code from the model and generating the model from the code seem to be two different, complex problems all on their own.

I can generate code from my model, but sometimes it is not feasible to regenerate code from a model due to code modifications that occur when the code is actually deployed.

How do you guys handle these activities?

  • by twunde on 7/13/2015, 3:51:56 AM

    I typically will generate basic code from a model and then after I make modifications I regenerate documentation and the model. To make a 2-way mapping really work you for you would have to separate generated code from code that you modify.

  • by KNoureen on 7/13/2015, 1:52:05 AM

    I guess that depends on your toolchain.

    For Java, I use Maven which have some powerful tools (Maven Site) to create test-reports, documentation, api-docs, coverage reports, diagrams and much more. It's also easy to extend yourself.

  • by Seb86 on 7/13/2015, 2:28:34 AM

    A great tool is Swagger, very useful is your app has a REST API as a back-end.