Talk:Bitmap: Difference between revisions
→Amount of comments: Comments are good where they add clarity. Code Golf is sometimes in the eye of the beholder!
(→Amount of comments: Comments are good, code golf is not (on this site...)) |
(→Amount of comments: Comments are good where they add clarity. Code Golf is sometimes in the eye of the beholder!) |
||
Line 41:
::: I'd note that when doing several of the tasks, I've had to push my knowledge of my [[Tcl|chosen language]] quite hard and even on occasion learn a new library. But in all cases, the perfect solution is one that other users of the site can quickly read, understand, and learn to replicate, and not the shortest answer. After all, we're not playing Code Golf. —[[User:Dkf|Donal Fellows]] 15:56, 30 August 2009 (UTC)
:::: I think we're starting to get off topic here. The original question was about code documentation not about the length of code itself. Documentation/comments fall into two main categories for me. Documenting the purpose and user interface for the functions (how to use the code), and documenting what the code is doing (how the code solves the problem). If I want to use a function, it is frustrating not to know its purpose or how to use it. Documentation and especially (for me) examples of use are especially helpful in that situation. However I think what prompted the question (Avmich, please correct me if I'm wrong) was the removal of some lines that had been added describing the purpose and user interface for the verbs <tt>allocImage, fillImage, getPixels, setPixels</tt>. I removed those lines because in the context of this page and with the usage examples and the initial description of the basic data structure provided, I believe that the user interface is quite clear.
:::: The second category of documentation (description of what the code is doing) can be very helpful to someone trying to understand the approach that has been taken - see [[Happy_Number#J]]. In many cases a big increase in readability can be accomplished by the judicious naming of intermediate functions and objects.
:::: With regards to the Code Golf comment, I agree that the objective is not to show the shortest possible answer, and I understand that sometimes solutions, especially for a language like J, will be perceived by someone not familiar with it as an attempt at Code Golf. In most cases though I think that is a misconception and is simply due to the increased semantic density of the language achieved by its grammar and use of symbols to represent functions and operators. This is similar to the difference between the representation of a phrase or concept using one or two Chinese characters rather than a whole sentence in English. I don't know any Chinese and I don't expect to understand it without first learning the meaning of the individual symbols. On the other hand I admit that in many cases the readability of some solutions (especially for beginning users) could be improved by breaking up longer lines into shorter chunks and giving them appropriate names.--[[User:Tikkanz|Tikkanz]] 22:51, 30 August 2009 (UTC)
| |||