Documenting Rails App

Rails Forum
1

I’ve being thinking about about this for quite sometime now, how should one go about documenting a rails app in a higher level than code documentation ?

And I’m currently facing the exactly issue that first sparked that though in me, that is trying to find if there’s already some code on that app that does what I need to do.

Some context, I have started a new job on the past 3 weeks and I’m working on maintaining a relatively big app and I need to import some CSV data for a new client, looking through the code I found about 2 CSV importer classes with absolutely now documentation, I don’t know which one to use at all, which are they use cases (or even if they have the same use case and some dude just made the other because he didn’t know of the previous one?)

Another example, working on a way bigger app (almost 5x times bigger, based only on LOCs), I found out some JS duplication and extracted to a helpful class that would be useful on a lot of places, but how should I document it? Just adding comments wouldn’t help my teammates know that this code exists and that they should use it when they need to. Reading the commits help but having to keep all that ‘context’ is a burden.

1 Like
2

Rails has a rake task that will generate the rdoc for your application: rake doc:app. The challenge there is getting your co-workers to write rdoc.

I’m a pretty big proponent of writing meaningful, high level rdoc; here’s what this is for, and some examples. Getting other developers on board with that is hard, because of all the years we’ve heard that ‘code should be self documenting’ or ‘the tests are the documentation’.

I also try to write thorough ‘documentation’ of changes in my git commits. I started doing that after reading this post: http://mislav.net/2014/02/hidden-documentation/

Again, getting other people on board with this is difficult, but I’ve found it extremely helpful.

1 Like
3

Yeah, I did saw other thread here that someone (maybe you?) pointed to that documentation on git commits, I really think that this is a good idea and I try to do it myself but again it’s useful when you’re inspecting code, I’m more interested in the perspective of a new developer joining a team and getting a overview of which features/helper the system already have.

Maybe the RDoc task is the way to go indeed, I was just wondering if there was any other ways, or even if anyone have a open source app that has those. I tried a quickly look at discourse, redmine and others and didn’t find.

1 Like
4

If you want to make code features easily grep-able you may consider using categorical comment markers all with the same format. Array-sort, JSON-sort, JavaScript-sort, jQuery-sort. Then to see what specialized sort methods you have you can simply grep -nR [-]sort

> grep -nR [-]sort
example.txt:1:JSON-sort
example.txt:2:jQuery-sort
example.txt:3:JavaScript-sort
example.txt:4:Array-sort

This returns the file, line number, and section of code from your grep search. And if you’ve properly rDoc’d the same section you labelled the search tag the documentation is right there as well. Following this pattern Array#reverse would also be categorized as Array-sort since reversing is in the sorting class.

1 Like