Why arent Unity C# code commented?

In ANY textbook about programming it always states how it's important to comment your code.

I find it extremely frustrating that when I look up examples in the Unity documentation, the C# examples are just pieces of code.. that has NO explanation of what that code is supposed to do!?!?

How does this make sense?

 

Not really. This particular piece of received wisdom was challenged way back when the eXtreme Programming movement was in full swing, which advocated the notion of self-documenting code as an alternative to excessive commenting that often degenerated into restating the code in prose form.

Usually the context answers the question of what is being done. and the examples themselves are simple enough so that the how is self-evident.

I haven't run into any examples where it didn't make sense, but I admit that I haven't gone through every code snippet in the documentation. Can you provide an example or two of code snippets that you found particularly mystifying? I'm sure the documentation team would appreciate the feedback.

 

Funny... just today I opened the API to read some math functions e.g. Mathf.Abs(), and the C# example did not contain any comments. I was like "huh?" - because the text on the documentation only said to "return an absolute value". But what is an absolute value? Sometimes I mix it up with rounding functions, and need to lookup the API.

Then I went to the JS tab and tadaaa... nice comments all the way in the example code - and only the example comments showed what this function does. Not wanting to start a discussion about *that* again, but if UT is overburdened maintaining all languages with the same care, they should just focus on a single one.

 

They have an automated code conversion tool, so they only write code for one language. They're aware of the disappearing comments and are fixing it.

--Eric

 

At first I used to wonder why some examples are done in JavaScript and why some are done in C# and not both.

But I decided not to gripe about it, because Boo users probably lack documentation examples the most compared to UnityScript and C# users, and as a C# user I'm fairly grateful for the documentation available in this language.

 

Documentation going forward will be C# centric and docs will have comments.

 

The mods have it spot on. We've always written examples in JS, and use a conversion tool to spit them out into C# and boo. The tool doesn't process comments, because it's based on our JS compiler, which, as every good compiler knows, ignoring comments is step one. We know that's a bit rubbish. Since c# is becoming more popular, new examples are written in c# and we have a tool that'll spit out commented JS from it. So we're going through a process of converting the JS into commented c#, deleting the JS, and converting the commented c# into commented JS. I know that *sounds* a bit rubbish. But it will be better. Separately we have a plan to actually get the script reference source code (I mean the data we use to generate the script reference from) on a bitbucket/github thing to let our users help us make the docs better. I personally think that the c# and JS script examples should be decoupled, so the community can write whatever examples they want, and not have to worry how the conversion tools work. But we'll see where we end up.

 

Some advise to the devs writing the code examples (gosh, I am feeling old now): If you find you need to document the code more, make it shorter instead.

Lots of sample are way too long and have lots of code lines not needed to present the piece documented with the example. Edit: I am speaking of "code examples in lots of other pages, like MSDN. Unity code examples are nice, short and precise. Keep up the good work"

If you strive for "complete compilable examples" instead of "minimalistic core ideas" (e.g. as its standard in older MSDN documentation), then what about some system where you as the writer of the example can mark some portion of the code. Only this portion will be displayed when loading the page in the first place and the "surrounding boilerplate code" will be shown when pressing some small "show me context" - icon.

 

No.

Your argument only ever, ever applies to real world code, not code you learn from in documentation.

The MSDN documentation could benefit quite a bit from some documentation. It is OK to offend an expert if it's documentation. Unity has a wide range of users from artists with almost no programming experience right up to expert users. If an expert user is upset by documentation having too many comments, then that is the lesser evil by far.

The point of documentation is to empower people new to the command or technique within Unity.

 

Hm, actually I would say the opposite. My argument only works for documentation code examples, where you usually want to demonstrate one tiny fracture of a whole program in order to give an usage of the particular feature you are documenting. It is insane for real-world code to only strive for minimal amount of visible code.

To be extra clear: I am speaking of the code examples inside the API documentation. I am NOT speaking of comments inside example projects. They should not be "minimalistic", but more like "real-world comments".

Also, I did not want to cricize the current code examples of the current API documentation. They are awesome in their length and scope and other documentations should use Unity API code examples as an example (harhar)

You mean "benefit ... from some comments"? If so, I disagree. They would benefit from more precise and focused examples, which can be excerpts from larger demo-projects, but currently many code examples are just copy-pastes of a whole demo project.

I take that as a compliment. . But you got a point here. Comments in general provide much different value to different experience groups. For many coders, its easier to read comments than to read code.

So let me try again:

"If you find you need to document the code more, this is a big sign that - additionally to comment - you should consider to make it shorter as well. The need for lots of comments often indicates too much context. Too much context destroys focus.

Although the lots of context can be awesome to provide an 'whole working example', so consider mark the exact code that is relevant to the current documented function and hide the surrounding (necessary) context by default with an easy-to-find 'show context' button."

Better?

 

I'd like to see some website like Unity Answers for providing comments to the API doc. I mean.. an community-driven system where you can add examples (and in general documentation text). For new users, other community users with higher reputation have to approve the text first. Also, you could add bounties to currently poorly documented sites or up/down rate provided documentations.

I would surely contribute over now and then..

 

I kind of hate the typical MSDN code examples, since they tend to make long, involved scripts when all I want to see is the function being used in context. If I have to spend a long time hunting for the function that's supposed to be illustrated, the code example has failed as far as I'm concerned. Usually just a code snippet is fine.

--Eric

 

That's what we'll use bitbucket/github for.

 

Hm.. can you elaborate on how this might work?

 

The material we use to generate the script reference docs are XML files. These contain the descriptions of the parameters, types, usage, etc, and the examples. When we make a build, these XML files are consumed to make the HTML pages. We're talking about having these XML files on a open source server, so customers can contribute.

(I think it's just regular open source stuff that's used all over the place these days, just for docs, not source.)

 

Ah... hm. Thats a good starting point, but I am not sure whether this will work as well as it could be.

I am most concerned about the round-trip times from writing some documentation until it finally appears on the website (has to go through a checkin+push, pull request, getting actually pulled, build in the next version and finally published to the website).

Anything longer than half an hour is killing the immediate gratification that you usually get in Wikis when you see the result of your labour shining on the website. Anything longer than a day is severly harming any feedback/update/feedback cycle.


Next, IMHO "Da famouse Web 2.0" TM is as much about "being able to contribute" as it is about "having fun while contributing".

Where is the "Graham liked this" buttons in a git repository?
Where is the "achievement 'Edited page after 2am'" page?
Where is the "73 people requested documentation for this feature" function?
Where is the "there are 500 points bounty for providing an example code"?
Where is the "you levelled up to 'Awesome Documenter Level 3'"?

I hope you get what I mean? It is very easy to just dismiss all these things and say "C'mon, we are all grown up."

Then again.. Apps that display growing flowers or make you "gaining nature points and level up in Environment Level" when you drive ecologically are a lot more effective that apps that just display the current "$ per minute".. Showing a sad smiley face if you drive too fast in a speed-restricted zone works far better than displaying the current and allowed speed. Stuff like this works. It really does!



Finally.. Editing XML files instead of some markup language is not the most fun I had in my work life so far... feels so... 90ish.. Definetely not everyones taste to install GIT, use Notepad to edit some obscure syntax and go though the whole commit+push+pull request cycle.


Maybe you can get good things from both worlds? Extract the structure scheme from the XML and the source code (e.g. the function name itself, the type of the return value, which parameter exist and their names). But have the actual description be some wiki-styled website.

The original description is always retrievable, e.g. with some "show official description" - button. But it can be replaced by the community instantly (or allow the community only to add remarks to the 'official version', if you're a chicken ). You can automatically extract and upload good changes (based on "likes/upvotes") to the "official" docs. Then, plug the Unity Answers infrastructure behind it (with all the silly stuff like badges, reputation and what not).

Doesn't have to be finished all in one go, of course.

 

Well, the round time trip will depend mostly on the validation of the source code, and the spelling and grammar of the text. That will take some review process. We're not doing this to make customers excited at seeing their lines of code appear on our website inside a few minutes. And if people want to do this for the buzz, then that's probably not the right approach. We do want some way of rewarding contributors, of course. If XML isn't fun, then sorry.

 

Oh... Why not let the community help fixing the spelling and grammar? There are probably a thousand times more people who can provide good documentation and example code albeit with spelling errors in the text than there are people who can provide good documentation and example code AND have correct spellings.

That is sad to hear. Not because I think you should do it "to make customers exited". But because you should do this to get good and quality documentation in the fewest amount of work for Unity. Social features are not the end, they are the means. Maybe my last post was too childish to get the point around.


Anyway.. its OK. Actually, the current existing documentation is quite good. The examples are very spot-on. Most of the time I got the necessary information in a couple of seconds. If you get the manpower together to document all the remaining features as well, then everything will be fine and awesome .

And yes, I can see your point in not wanting to give up control over the final API documentation to anyone. After all, its kind of "the official reference", so even if there would be poorly written pages for currently undocumented things, that could hurt the overall trust in the documentation and people might just ask to only "show the official description".

 

We will. The text is in the XML files that the users can edit. Any changes that the community offer will get reviewed and published.

 

We want community man-power to help make it all better.

 

I'd be nice if the default documentation chosen was C#.