www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [OT] I am a developer and I hate documentation

reply Kagamin <spam here.lot> writes:
Article: 
https://dzone.com/articles/why-developers-write-horrible-documentation-and-ho
Also: 
https://www.reddit.com/r/programming/comments/4y6pws/why_video_documentation_isnt_the_answer/
Aug 18 2016
next sibling parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 08:40:23 UTC, Kagamin wrote:
 Article: 
 https://dzone.com/articles/why-developers-write-horrible-documentation-and-ho
 Also: 
 https://www.reddit.com/r/programming/comments/4y6pws/why_video_documentation_isnt_the_answer/
I'm not convinced. The resulting video may be more confusing than no documentation at all. Apart from that, I don't wanna talk (poor listeners) or be "watched" (poor me) while programming. Looks like they're trying to market video-doc platforms and apps, this, or companies in the USofA are too lazy to go through the code that the NSA ripped for them. No, let the industrial spies do at least some work - let them be industrious spies!
Aug 18 2016
parent Kagamin <spam here.lot> writes:
On Thursday, 18 August 2016 at 09:29:02 UTC, Chris wrote:
 I'm not convinced.
Just liked the catchy title :) Video instead of docs is terrible indeed.
Aug 18 2016
prev sibling next sibling parent reply Shachar Shemesh <shachar weka.io> writes:
On 18/08/16 11:40, Kagamin wrote:
 Article:
 https://dzone.com/articles/why-developers-write-horrible-documentation-and-ho

 Also:
 https://www.reddit.com/r/programming/comments/4y6pws/why_video_documentation_isnt_the_answer/
Documentation is like sex. When it's good, it's very good. When it's bad..... it's still better than nothing.
Aug 18 2016
parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 09:49:17 UTC, Shachar Shemesh 
wrote:

 Documentation is like sex.

 When it's good, it's very good.

 When it's bad..... it's still better than nothing.
Your comparison is not 100% correct. While those who enjoy making love are the same people who are doing it, writing docs is enjoyed by others, but not by the one(s) doing it.
Aug 18 2016
parent reply Seb <seb wilzba.ch> writes:
On Thursday, 18 August 2016 at 11:28:10 UTC, Chris wrote:
 On Thursday, 18 August 2016 at 09:49:17 UTC, Shachar Shemesh 
 wrote:

 Documentation is like sex.

 When it's good, it's very good.

 When it's bad..... it's still better than nothing.
Your comparison is not 100% correct. While those who enjoy making love are the same people who are doing it, writing docs is enjoyed by others, but not by the one(s) doing it.
Warning - this is has gone quite off-topic, so before you start to criticize the following sentence, let's better focus on the bigger issue here: documentation for most D packages is terrible. There is a fix: s/sex/porn/g
Aug 18 2016
parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 12:20:01 UTC, Seb wrote:
 On Thursday, 18 August 2016 at 11:28:10 UTC, Chris wrote:

 Warning - this is has gone quite off-topic, so before you start 
 to criticize the following sentence, let's better focus on the 
 bigger issue here: documentation for most D packages is 
 terrible.

 There is a fix: s/sex/porn/g
I knew this would come up, but it's not true either. Then you could also throw in (forced) prostitution etc. However, in one way documentation is how sex: more people talk about it than actually do it! Isn't there a way to auto-generate a minimal documentation with the help of the compiler? As in int myFunction(int a, int b) { if (a > -1) return a + b; return -1; } // auto-gen: Returns `int`, if `a` is greater than -1, else returns -1. Parameters: `int`, `int`; Returns `int`. Something like that.
Aug 18 2016
next sibling parent Stefan Koch <uplink.coder googlemail.com> writes:
On Thursday, 18 August 2016 at 13:19:13 UTC, Chris wrote:

 Isn't there a way to auto-generate a minimal documentation with 
 the help of the compiler? As in

 int myFunction(int a, int b)
 {
   if (a > -1)
     return a + b;
   return -1;
 }

 // auto-gen:
 Returns `int`, if `a` is greater than -1, else returns -1.
 Parameters: `int`, `int`; Returns `int`.

 Something like that.
Would you like a patch ? that will at least autogen Returns `int`, Parameters: `int a`, `int b`; No automatic Semantics though.
Aug 18 2016
prev sibling next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 18 August 2016 at 13:19:13 UTC, Chris wrote:
 Isn't there a way to auto-generate a minimal documentation with 
 the help of the compiler? As in
I think that would be useless for anything other than toy functions. You can just view the source and learn more than that. Good documentation tells you something that is hard to tell from the source alone... it tells you there's a forest among these trees. But even just plain tree thing, the doc can just list the prototype and have a view source thing rather than try to parse the code into English anyway.
Aug 18 2016
parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 14:31:47 UTC, Adam D. Ruppe wrote:
 On Thursday, 18 August 2016 at 13:19:13 UTC, Chris wrote:
 Isn't there a way to auto-generate a minimal documentation 
 with the help of the compiler? As in
I think that would be useless for anything other than toy functions. You can just view the source and learn more than that. Good documentation tells you something that is hard to tell from the source alone... it tells you there's a forest among these trees. But even just plain tree thing, the doc can just list the prototype and have a view source thing rather than try to parse the code into English anyway.
It would be a good starting point for documentation stubs, not a substitute for a proper, full-fledged documentation. The most annoying thing about writing docs is the amount of boilerplate, not the doc itself, cf: /** Find $(D value) _among $(D values), returning the 1-based index of the first matching value in $(D values), or $(D 0) if $(D value) is not _among $(D values). The predicate $(D pred) is used to compare values, and uses equality by default. Params: pred = The predicate used to compare the values. value = The value to search for. values = The values to compare the value to. Returns: 0 if value was not found among the values, otherwise the index of the found value plus one is returned. [...] */ If `Params` and `Returns` were generated automagically, at least as stubs, then it would be easier to write the "true" description, i.e. if you had something like: /** <Description here> Params: pred = value = values = Returns: (unit) 0 || index + 2 */
Aug 18 2016
next sibling parent Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 14:59:08 UTC, Chris wrote:


(unit) 0 || index + 1, that is.
Aug 18 2016
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 18 August 2016 at 14:59:08 UTC, Chris wrote:
 It would be a good starting point for documentation stubs, not 
 a substitute for a proper, full-fledged documentation.
Oh yeah, if it was in the source itself, I can see the point of that. IDEs can and probably should do that at least.
Aug 18 2016
prev sibling parent reply Marco Leise <Marco.Leise gmx.de> writes:
Am Thu, 18 Aug 2016 14:59:08 +0000
schrieb Chris <wendlec tcd.ie>:

 On Thursday, 18 August 2016 at 14:31:47 UTC, Adam D. Ruppe wrote:
 It would be a good starting point for documentation stubs, not a 
 substitute for a proper, full-fledged documentation. The most 
 annoying thing about writing docs is the amount of boilerplate, 
 not the doc itself, cf:
 
 /**
 Find $(D value) _among $(D values), returning the 1-based index
 of the first matching value in $(D values), or $(D 0) if $(D 
 value)
 is not _among $(D values). The predicate $(D pred) is used to
 compare values, and uses equality by default.
 Params:
      pred = The predicate used to compare the values.
      value = The value to search for.
      values = The values to compare the value to.
 Returns:
      0 if value was not found among the values, otherwise the 
 index of the
      found value plus one is returned.
 
 [...]
 */
 
 If `Params` and `Returns` were generated automagically, at least 
 as stubs, then it would be easier to write the "true" 
 description, i.e. if you had something like:
 
 /**
 <Description here>
 Params:
      pred =
      value =
      values =
 Returns:
      (unit) 0 || index + 2
 */
My take on it is to document the Params where they are declared: int mul2(int x /** the value to be multiplied by 2 */) { return 2*x; } People have been doing that in the past with or without documentation generators for the benefit that you don't need to repeat yourself and don't need to update the docs after an argument name refactoring. By the way, AFAIK someone implemented `code` as an alternative to $(D code) quite a while ago. So you can use that instead. I'd like ordered/unordered lists to also follow markup style one day. I find it more natural and readable than $(OL $(LI first item) $(LI another important thing) ) -- Marco
Aug 18 2016
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Fri, Aug 19, 2016 at 12:02:09AM +0200, Marco Leise via Digitalmars-d wrote:
[...]
 By the way, AFAIK someone implemented `code` as an alternative to $(D
 code) quite a while ago. So you can use that instead.  I'd like
 ordered/unordered lists to also follow markup style one day. I find it
 more natural and readable than
 
 $(OL
   $(LI first item)
   $(LI another important thing)
 )
[...] Sigh. Eventually we're just reinventing Markdown in ddoc. Why can't we just use Markdown (with some ddoc extensions) in the first place? T -- Let's not fight disease by killing the patient. -- Sean 'Shaleh' Perry
Aug 18 2016
next sibling parent reply karabuta <karabutaworld gmail.com> writes:
On Thursday, 18 August 2016 at 23:14:44 UTC, H. S. Teoh wrote:
 On Fri, Aug 19, 2016 at 12:02:09AM +0200, Marco Leise via 
 Digitalmars-d wrote: [...]
 By the way, AFAIK someone implemented `code` as an alternative 
 to $(D code) quite a while ago. So you can use that instead.  
 I'd like ordered/unordered lists to also follow markup style 
 one day. I find it more natural and readable than
 
 $(OL
   $(LI first item)
   $(LI another important thing)
 )
[...] Sigh. Eventually we're just reinventing Markdown in ddoc. Why can't we just use Markdown (with some ddoc extensions) in the first place? T
That will be way better, don't know why markdown is not used already. ..... Cant imagine how a compiler generated documentation for D templates will look like :)
Aug 18 2016
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 18 August 2016 at 23:50:34 UTC, karabuta wrote:
 That will be way better, don't know why markdown is not used 
 already.
ddoc is *significantly* older than markdown, especially for popular use. When ddoc came out, *it* was the "clean" syntax for inline docs. But then Walter fell a bit too much in love with it... Ddoc was poorly designed, Walter's lack of experience in web matters shows pretty clearly in it, but it wasn't necessarily a bad decision for its time, then it just got entrenched. If we wanted to move away from it, someone would have to write a new generator and fork the docs and do thousands of changes to bring them to a new system.... I don't know anyone crazy enough to do that. http://dpldocs.info
Aug 18 2016
parent reply Yuxuan Shui <yshuiv7 gmail.com> writes:
On Friday, 19 August 2016 at 01:32:55 UTC, Adam D. Ruppe wrote:
 On Thursday, 18 August 2016 at 23:50:34 UTC, karabuta wrote:
 That will be way better, don't know why markdown is not used 
 already.
ddoc is *significantly* older than markdown, especially for popular use. When ddoc came out, *it* was the "clean" syntax for inline docs. But then Walter fell a bit too much in love with it... Ddoc was poorly designed, Walter's lack of experience in web matters shows pretty clearly in it, but it wasn't necessarily a bad decision for its time, then it just got entrenched. If we wanted to move away from it, someone would have to write a new generator and fork the docs and do thousands of changes to bring them to a new system.... I don't know anyone crazy enough to do that. http://dpldocs.info
We should be able to automate this task if we do decide to move away from it. Can't be harder than converting C++ to D, right....?
Aug 18 2016
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 19 August 2016 at 02:49:41 UTC, Yuxuan Shui wrote:
 We should be able to automate this task if we do decide to move 
 away from it. Can't be harder than converting C++ to D, 
 right....?
Yeah. I'm being a bit facetious there: I actually already did it and the result is on my dpldocs.info site. There's still a few rough edges that I'm working on slowly but surely, but the bulk of the work has been done for a while.
Aug 18 2016
next sibling parent reply Sebastiaan Koppe <mail skoppe.eu> writes:
On Friday, 19 August 2016 at 02:52:54 UTC, Adam D. Ruppe wrote:
 Yeah. I'm being a bit facetious there: I actually already did 
 it and the result is on my dpldocs.info site.

 There's still a few rough edges that I'm working on slowly but 
 surely, but the bulk of the work has been done for a while.
Haven't look at it for a while, but you did a pretty good job! Any chance of it becoming official?
Aug 19 2016
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 19 August 2016 at 07:33:42 UTC, Sebastiaan Koppe wrote:
 Any chance of it becoming official?
Not directly, the core team is married to their old ways.
Aug 21 2016
prev sibling parent jmh530 <john.michael.hall gmail.com> writes:
On Friday, 19 August 2016 at 02:52:54 UTC, Adam D. Ruppe wrote:
 Yeah. I'm being a bit facetious there: I actually already did 
 it and the result is on my dpldocs.info site.

 There's still a few rough edges that I'm working on slowly but 
 surely, but the bulk of the work has been done for a while.
I remember looking at this before and thinking those docs looked really good.
Aug 19 2016
prev sibling parent Dicebot <public dicebot.lv> writes:
From: Dicebot <public dicebot.lv>
Newsgroups: d,i,g,i,t,a,l,m,a,r,s,.,D
Subject: Re: [OT] of [OT] I am a developer and I hate documentation
References: <cwizyelstmbrguyuckzo forum.dlang.org>
 <np40at$jol$1 digitalmars.com> <ojlrrbhcoszrmtkzfgab forum.dlang.org>
 <frdxlwkoknvmmudpubii forum.dlang.org> <egnbtcqvipvyptpqtkae forum.dlang.org>
 <cjalrjozwxahnqatutzu forum.dlang.org> <yznppnmbrxaednsnwneu forum.dlang.org>
 <20160819000209.18113e98 gmx.de>
 <mailman.4.1471562536.3111.digitalmars-d puremagic.com>
 <iippfmrkzjyyrhjydmtl forum.dlang.org>
In-Reply-To: <iippfmrkzjyyrhjydmtl forum.dlang.org>

--SShH73fTn2HapJWMcaOkVC48a5XBQ6OK1
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

On 08/19/2016 02:50 AM, karabuta wrote:
 Sigh.  Eventually we're just reinventing Markdown in ddoc. Why can't
 we just use Markdown (with some ddoc extensions) in the first place?


 T
=20 That will be way better, don't know why markdown is not used already.
There is https://github.com/kiith-sa/harbored-mod which supports markdown in addition to base ddoc. We are actually switching to it as a standard internal documentation generator at Sociomantic. --SShH73fTn2HapJWMcaOkVC48a5XBQ6OK1--
Aug 19 2016
prev sibling parent Seb <seb wilzba.ch> writes:
On Thursday, 18 August 2016 at 23:14:44 UTC, H. S. Teoh wrote:
 On Fri, Aug 19, 2016 at 12:02:09AM +0200, Marco Leise via 
 Digitalmars-d wrote: [...]
 By the way, AFAIK someone implemented `code` as an alternative 
 to $(D code) quite a while ago. So you can use that instead.  
 I'd like ordered/unordered lists to also follow markup style 
 one day. I find it more natural and readable than
 
 $(OL
   $(LI first item)
   $(LI another important thing)
 )
[...] Sigh. Eventually we're just reinventing Markdown in ddoc. Why can't we just use Markdown (with some ddoc extensions) in the first place? T
In my childish naivity I opened an enhancement request recently: https://issues.dlang.org/show_bug.cgi?id=16112
Aug 18 2016
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Aug 18, 2016 at 01:19:13PM +0000, Chris via Digitalmars-d wrote:
[...]
 Isn't there a way to auto-generate a minimal documentation with the
 help of the compiler? As in
 
 int myFunction(int a, int b)
 {
   if (a > -1)
     return a + b;
   return -1;
 }
 
 // auto-gen:
 Returns `int`, if `a` is greater than -1, else returns -1.
 Parameters: `int`, `int`; Returns `int`.
 
 Something like that.
Nah, this kind of so-called "documentation" is no better than reading the code itself. It's just like code comments that basically repeat what the code does, which is useless because you can already read the code. What you want are comments / docs that explain things that are *not* immediately obvious from the code, such as: - High-level discussion of *why* this code does what it does; - Relevant examples of *how* to use it, in the context of what it was intended for (i.e., not just a dumb `auto x = myFunc(123);` which says nothing about how to use it in real life). - *When* to use this code, and when not to use it. - Any gotchas to watch out for (e.g. this function may return the wrong result if the input is poorly-conditioned) - What algorithm(s) are used to compute the result, and why said algorithms were chosen, their advantages / disadvantages, etc. Even more obvious parts of the docs also need proper explanation. For example, compare: /** * Repeats a string. * Params: * x = a string * y = an int * Returns: a string. */ string repeat(string x, int y) { ... } versus: /** * Repeats a string by the specified number of times. * Params: * x = the string to repeat * y = the number of times to repeat the string * Returns: the input string repeated y times. */ string repeat(string x, int y) { ... } The first example has completely worthless docs, because it says nothing that the function signature itself doesn't already tell you. The second is better because it describes what the parameters are supposed to signify, and defines the result more precisely. Autogenerated docs give you the first kind of docs. You need human effort to write the second kind. T -- In theory, there is no difference between theory and practice.
Aug 18 2016
parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 15:12:52 UTC, H. S. Teoh wrote:

 Nah, this kind of so-called "documentation" is no better than 
 reading the code itself. It's just like code comments that 
 basically repeat what the code does, which is useless because 
 you can already read the code.

 What you want are comments / docs that explain things that are 
 *not*
 immediately obvious from the code, such as:
 - High-level discussion of *why* this code does what it does;
 - Relevant examples of *how* to use it, in the context of what 
 it was
   intended for (i.e., not just a dumb `auto x = myFunc(123);` 
 which says
   nothing about how to use it in real life).
 - *When* to use this code, and when not to use it.
 - Any gotchas to watch out for (e.g. this function may return 
 the wrong
   result if the input is poorly-conditioned)
 - What algorithm(s) are used to compute the result, and why said
   algorithms were chosen, their advantages / disadvantages, etc.

 Even more obvious parts of the docs also need proper 
 explanation. For example, compare:

 	/**
 	 * Repeats a string.
 	 * Params:
 	 *	x = a string
 	 *	y = an int
 	 * Returns: a string.
 	 */
 	string repeat(string x, int y) { ... }
However, this would be very useful as a stub. To write "Repeats a string by the specified number of times." is trivial. Often a function can be explained in one or two sentences, like "Saves output as WAV file. Returns true on success, otherwise false.". The rest is a real pita. All that boilerplate for bool saveWAV(string path) { // ... if (...) return true; return false } That's the real killer. Hey, if dmd can generate files with code coverage, it could generate files with doc stubs.
Aug 18 2016
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Aug 18, 2016 at 03:38:03PM +0000, Chris via Digitalmars-d wrote:
 On Thursday, 18 August 2016 at 15:12:52 UTC, H. S. Teoh wrote:
 Nah, this kind of so-called "documentation" is no better than
 reading the code itself. It's just like code comments that basically
 repeat what the code does, which is useless because you can already
 read the code.
 
 What you want are comments / docs that explain things that are *not*
 immediately obvious from the code, such as:
 - High-level discussion of *why* this code does what it does;
 - Relevant examples of *how* to use it, in the context of what it was
   intended for (i.e., not just a dumb `auto x = myFunc(123);` which says
   nothing about how to use it in real life).
 - *When* to use this code, and when not to use it.
 - Any gotchas to watch out for (e.g. this function may return the wrong
   result if the input is poorly-conditioned)
 - What algorithm(s) are used to compute the result, and why said
   algorithms were chosen, their advantages / disadvantages, etc.
 
 Even more obvious parts of the docs also need proper explanation. For
 example, compare:
 
 	/**
 	 * Repeats a string.
 	 * Params:
 	 *	x = a string
 	 *	y = an int
 	 * Returns: a string.
 	 */
 	string repeat(string x, int y) { ... }
However, this would be very useful as a stub. To write "Repeats a string by the specified number of times." is trivial. Often a function can be explained in one or two sentences, like "Saves output as WAV file. Returns true on success, otherwise false.". The rest is a real pita. All that boilerplate for bool saveWAV(string path) { // ... if (...) return true; return false } That's the real killer. Hey, if dmd can generate files with code coverage, it could generate files with doc stubs.
[...] Shouldn't that be the job of the IDE? If the IDE always generated doc stubs for non-private functions, that could be good encouragement for the coder to actually fill it in! Esp. if the stub reads: /** * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Params: * x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN */ int myFunc(int x, int y) { ... } :-P T -- "Holy war is an oxymoron." -- Lazarus Long
Aug 18 2016
next sibling parent reply ketmar <ketmar ketmar.no-ip.org> writes:
On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:
 if the stub reads:

 	/**
 	 * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Params:
 	 *	x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 *	y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 */
 	int myFunc(int x, int y) { ... }

 :-P
i assure you that programmers will still be too lazy to fill the docs. but they *will* spend alot of time rebuilding (or hex-editing if there is no source) their IDE to replace the message.
Aug 18 2016
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Aug 18, 2016 at 04:56:32PM +0000, ketmar via Digitalmars-d wrote:
 On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:
 if the stub reads:
 
 	/**
 	 * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Params:
 	 *	x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 *	y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 */
 	int myFunc(int x, int y) { ... }
 
 :-P
i assure you that programmers will still be too lazy to fill the docs. but they *will* spend alot of time rebuilding (or hex-editing if there is no source) their IDE to replace the message.
Haha, too true! T -- Without geometry, life would be pointless. -- VS
Aug 18 2016
parent reply Chris <wendlec tcd.ie> writes:
On Thursday, 18 August 2016 at 17:23:09 UTC, H. S. Teoh wrote:
 On Thu, Aug 18, 2016 at 04:56:32PM +0000, ketmar via 
 Digitalmars-d wrote:
 On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:
 if the stub reads:
 
 	/**
 	 * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Params:
 	 *	x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 *	y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 */
 	int myFunc(int x, int y) { ... }
 
 :-P
i assure you that programmers will still be too lazy to fill the docs. but they *will* spend alot of time rebuilding (or hex-editing if there is no source) their IDE to replace the message.
Haha, too true! T
It is true. After all, it's all about writing code and hacking. "Look now it says 'THE PROGRAMMER IS COOL'! It only took me 3 hours to figure out how to replace the message. I'll write a blog about it! => reddit => flame war => please mark as OT ..." But it is like everything else: nice to have, even if you don't use it _all the time_.
Aug 19 2016
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Fri, Aug 19, 2016 at 10:50:20AM +0000, Chris via Digitalmars-d wrote:
 On Thursday, 18 August 2016 at 17:23:09 UTC, H. S. Teoh wrote:
 On Thu, Aug 18, 2016 at 04:56:32PM +0000, ketmar via Digitalmars-d
 wrote:
 On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:
 if the stub reads:
 	/**
* THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Params: * x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN */ int myFunc(int x, int y) { ... }
 :-P
i assure you that programmers will still be too lazy to fill the docs. but they *will* spend alot of time rebuilding (or hex-editing if there is no source) their IDE to replace the message.
Haha, too true! T
It is true. After all, it's all about writing code and hacking. "Look now it says 'THE PROGRAMMER IS COOL'! It only took me 3 hours to figure out how to replace the message. I'll write a blog about it! => reddit => flame war => please mark as OT ..."
[...] And if the pro-doc-ers are equally "cool", there would be an arms race where the stub is encrypted with strong encryption to prevent tampering, and the programmers would figure out ways of bypassing it, and develop an entire subculture of IDE-cracking and doc avoidance. :-P T -- Never trust an operating system you don't have source for! -- Martin Schulze
Aug 19 2016
parent reply Marco Leise <Marco.Leise gmx.de> writes:
Am Fri, 19 Aug 2016 07:34:51 -0700
schrieb "H. S. Teoh via Digitalmars-d"
<digitalmars-d puremagic.com>:

 On Fri, Aug 19, 2016 at 10:50:20AM +0000, Chris via Digitalmars-d wrote:
 On Thursday, 18 August 2016 at 17:23:09 UTC, H. S. Teoh wrote:  
 On Thu, Aug 18, 2016 at 04:56:32PM +0000, ketmar via Digitalmars-d
 wrote:  
 On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:  
 if the stub reads:  
 	/**  
* THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Params: * x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN */ int myFunc(int x, int y) { ... }
 :-P  
i assure you that programmers will still be too lazy to fill the docs. but they *will* spend alot of time rebuilding (or hex-editing if there is no source) their IDE to replace the message.
Haha, too true! T
It is true. After all, it's all about writing code and hacking. "Look now it says 'THE PROGRAMMER IS COOL'! It only took me 3 hours to figure out how to replace the message. I'll write a blog about it! => reddit => flame war => please mark as OT ..."
[...] And if the pro-doc-ers are equally "cool", there would be an arms race where the stub is encrypted with strong encryption to prevent tampering, and the programmers would figure out ways of bypassing it, and develop an entire subculture of IDE-cracking and doc avoidance. :-P T
Guys if you have too much free time, go fix some compiler bugs. :D -- Marco
Aug 19 2016
parent Chris <wendlec tcd.ie> writes:
On Friday, 19 August 2016 at 15:10:55 UTC, Marco Leise wrote:
 Guys if you have too much free time, go fix some compiler bugs. 
 :D
First we'll have to generate the documentation for it :)
Aug 19 2016
prev sibling parent Fool <fool dlang.org> writes:
On Thursday, 18 August 2016 at 16:17:15 UTC, H. S. Teoh wrote:
 	/**
 	 * THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Params:
 	 *	x = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 *	y = THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 * Returns: THE PROGRAMMER WAS TOO LAZY TO FILL THIS IN
 	 */
 	int myFunc(int x, int y) { ... }
s/\<THE PROGRAMMER\>/$USERNAME/g /** * S. TEOH WAS TOO LAZY TO FILL THIS IN * Params: * x = S. TEOH WAS TOO LAZY TO FILL THIS IN * y = S. TEOH WAS TOO LAZY TO FILL THIS IN * Returns: S. TEOH WAS TOO LAZY TO FILL THIS IN */ int myFunc(int x, int y) { ... } :-P
Aug 18 2016
prev sibling parent ketmar <ketmar ketmar.no-ip.org> writes:
On Thursday, 18 August 2016 at 15:38:03 UTC, Chris wrote:
 However, this would be very useful as a stub.
and it will stay as stub forever. more than that: with autogenerated stubs people will start answer: "stop complaining about documentation! i have each my function documented, can't you see?!"
Aug 18 2016
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Aug 18, 2016 at 08:40:23AM +0000, Kagamin via Digitalmars-d wrote:
 Article:
 https://dzone.com/articles/why-developers-write-horrible-documentation-and-ho
 Also: https://www.reddit.com/r/programming/comments/4y6pws/why_video_documentation_isnt_the_answer/
The first article claims that video documentation is better. I think that's BS. Making video docs takes MUCH MORE resources and effort than written docs, meaning that it's even less likely to get done, and less likely to be kept up-to-date as the code inevitably changes. I agree with the second article that video docs aren't the answer. I much rather have poorly-written docs that are searchable than video docs that are unsearchable. I mean, come on, do you seriously want to watch a video repeatedly every time you need to look up one specific detail buried somewhere therein? That's ridiculously inefficient. Give me written docs any day. T -- Just because you can, doesn't mean you should.
Aug 18 2016
prev sibling parent karabuta <karabutaworld gmail.com> writes:
On Thursday, 18 August 2016 at 08:40:23 UTC, Kagamin wrote:
 Article: 
 https://dzone.com/articles/why-developers-write-horrible-documentation-and-ho
 Also: 
 https://www.reddit.com/r/programming/comments/4y6pws/why_video_documentation_isnt_the_answer/
Ha ha ha! I read the article :) What sort of thinking went into writing this article? Videos as documentation? So when you want to understand a single function, you just search for that section in the video which a bet will take more time. If you cannot write well (with all the corrections you can make when writing), how can you speak well in one shot. So the question is, "Are programmers good verbal communicators than writers or vice versa"?
 "Damian Wolf is an tech enthusiast and marketing professional. 
 He loves to write about cloud technology, knowledge management 
 and business performance.".
Mhmm, that's why.
 Developers Don't Need Documentation
....
 Video documentation is the answer.
This article is dangerous
Aug 18 2016