- Home /
[Solved] What is the best way to document your code on a mac?
Hello Devs,
I am a mac user and I use Mono-Develop with C#. Now I do follow the coding conventions. For example the conventions I follow are of based on this UnityGems link.
Now at some point, I might have to give my project to someone else to work on it. Hence I wish to document my script as I go. In this way, it would be organized & helpful for me and for the rest who come by. I would like to know, if there is any methodology to adopt for documenting the code. Just to let you know, my knowledge base on documenting the code is absolutely zero.
My perception is this, I might have a lot of variables and methods inside a class. I would like to have a detailed description of all the methods and variables on a single piece of document.
I have also heard about some third-party documentation providers such as dOxygen.
Thank you,
regards, Karsnen.
You could create documentation with Visual Studio, I guess it is still possible.
Answer by $$anonymous$$ · Nov 30, 2012 at 08:40 PM
Honestly there is no one "standard" as such to follow when it comes to code documentation :) The way you name classes, variables, methods or in what way you choose to place them in classes and so on. There really isn't any standard. What you will mostly find is that developers have entirely different opinions about what's good and bad.
Coding coventions can be nice to have when you work alone simply to add some consistency in code documentation and structure, so it becomes easier for yourself to navigate through and understand projects which you've been away from for a while. Trust me, do not underestimate the power of proper conventions even if it is only for yourself. I said this with many painful regrets when going back and updating older commercial products... ;)
When working in companies or with other people on a day to day basis, coding convention is less about everyone agreeing one what's awesome and what's bad (almost always impossible), and more about simply finding a standard for everyone to follow so all coders follow a convention everyone else on the team will understand quickly, thus reducing time understanding code and increasing time producing code (in an optimal situation).
In your specific situation, I would not advice you to actually try and conform to what 100's of developers all around the web says just so you can try and please whatever developer you would like to pass your code on to. It simply won't be possible to please everyone ;)
Instead, read around on the internet and look at articles about general guide-lines which is more or less considered good practice in most developer circles. Write your rules down in a document and start to follow them. If you do this properly, it will create consistency for yourself which is vital, and furthermore you should have code which is also easier for others to get into later on.
You can use third-party software such as doxygen. I've used it several times and it's a great tool for generating HTML based navigation of classes and descriptions, as well as visuals of class hierachies, so by all means go for it. I would recommend that you provide this in case of handing it over to other developers later on, as it is easier to get an overview through an HTML document than a pure coding project.
Good luck!
PastryGood -> Thank you for your answer and information. I have one more question, is there any other applications which could document your code like dOxygen. Probably something that would produce a xml document?
Glad I could help :) As a matter of fact I'm pretty sure that Doxygen provides X$$anonymous$$L output as a format too, but unfortunately I haven't used that part of it. Specifically they write about it in the manual at this direct link: http://www.stack.nl/~dimitri/doxygen/customize.html#xmlgenerator
Besides that I'm not quite sure about other tools, you will have to look around if doxygen won't do the trick I'm afraid. But take a look at the above link first :)
$$anonymous$$y $.02: The problem I've seen with Doxygen is people get lazy, thinking that it will 'document' the code. All it does is hyperlink it and make it 'pretty'. Nothing beats good comments. A lot of folks put a little data dictionary and summary of function on each function/class. That's good. Also comment in code a lot. You think you write code that is self-documenting? $$anonymous$$aybe to you, but to nobody else. Code isn't done until its so commented, anyone can read and understand it.
Definitely have to agree with you there. Doxygen should be the product of well-documented code! Although I will agree with you that code is never really self-documenting (not when you get to your algorithms and such) I will also have to say that putting in too much documentation is also dangerous. The more documentation you add, the harder it becomes to maintain it. Quick hot-fixes or changes in code coupled with being too lazy to change comments/newly added parameters or changed method names or what have you can also quickly lead to the demise of what documentation is there to help you with! Suddenly you have documentation that doesn't match the code. Your code is the only thing which is ALWAYS up to date in your code, it is the single most valuable thing to describe what your application actually does. It is your job to keep the documentation up to date. $$anonymous$$eep a fine balance between to much and too little documentation. This can be hard to keep :)
Good point PastryGood. It can be a challenge to be disciplined enough to keep the internal docs up to date. Part of the job I guess.