p-lang thread: (now (have you (problems two)))

The Something Awful Forums > Discussion > Serious Hardware/Software Crap > YOSPOS > p-lang thread: (now (have you (problems two)))

«‹›1784 »

Nomnom Cookie: Aug 30, 2009

Shaggar posted:

javadoc type docs are almost optional if your api is simple enough and doesn't have retarded method names.

except that a lot of java libs nowadays define their own exception hierarchy descended from runtimeexception so you need the javadoc to find out wtf

# ? Apr 26, 2013 23:37

Adbot: ADBOT LOVES YOU

# ? May 23, 2024 17:43

abraham linksys: Sep 6, 2010

one of the things i like about ember.js is that they do a decent job of pairing getting started guides, task-specific guides, conceptual guides, and then a shitload of api documentation built w/ yuidoc (which is javadoc for any language with /* block comments */)

not all of those things are very well-done, but at least they're trying to be more robust than most

# ? Apr 26, 2013 23:40

compuserved: Mar 20, 2006; Nap Ghost

MononcQc posted:

Yes and no. The question is about the same topic, but the answer you expect isn't the same. It's possible to get the answer to the higher-level question using the API doc, the same way it's possible to get it from the source. It doesn't mean it's desirable, though.

It's like when you want to know "is that TV show good?" and the sperglord in the room gets into a 45 minutes tirade about cylons and their impact on popular culture. You get the answer you wanted, but it's buried in a shitload of information you never asked for nor needed to begin with.

The person or team who produces the code and the javadoc should also provide a simple tutorial, instructions on how to get started, how to install and/or configure the app or library, or point to a place that shows how to. It should tell the user why it was written, what it does, etc.

The example I posted above (PropEr) has many levels of docs: getting started (installing, running a minimal case), tutorials, examples, a javadoc equivalent, a FAQ, tips, links to slides and presentations, etc. They're all on site, by the few people who work on the project. That is good documentation, and even then, using the library isn't always trivial due to its inherent complexity.

There isn't some kind of magic world outside of the source code and its direct derivatives that suddenly murders developers and forces them to avoid it at all costs. If you're able to talk to a user one on one, or to someone on IRC, or over e-mail, and that you explain to them how to use your application or library, then you know that your javadoc is likely a POS for whatever use they have in mind and you need to go fix it. Documentation is about transferring information from a person A to a person B in order to save everybody the time that would be required to reverse-engineer the code. The more reverse-engineering a person has to do to figure things out, the more deficient your documentation is.

I don't expect every developer to go above and beyond and always present the best documentation in the world, but I'm generally fed up with the attitude that readable source is enough for everything.

Javadoc is good, but it's still limited in what it can be used for. A tutorial alone helps people start using your app/lib, but they're lost when there isn't more offered to them. There's more than one kind of users, and there should consequently be more than one kind of documentation.

thanks for this post, i enjoyed reading it

# ? Apr 26, 2013 23:57

Shaggar: Apr 26, 2006

Nomnom Cookie posted:

except that a lot of java libs nowadays define their own exception hierarchy descended from runtimeexception so you need the javadoc to find out wtf

anyone who does that should be murdered unless they have a damned good reason to do it

# ? Apr 27, 2013 00:00

Pardot: Jul 25, 2001

B-smooth posted:

thanks for this post, i enjoyed reading it

# ? Apr 27, 2013 00:15

Nomnom Cookie: Aug 30, 2009

Shaggar posted:

anyone who does that should be murdered unless they have a damned good reason to do it

i agree but i'll settle for decent docs

# ? Apr 27, 2013 00:25

Nomnom Cookie: Aug 30, 2009

exceptions coming from libs i write are unchecked but thats because if they were checked my coworkers would catch(Exception e) { e.printStackTrace(); } if they're unchecked then they just ignore exceptions and they can bubble up to a sane catch block (also written by me)

# ? Apr 27, 2013 00:30

Max Facetime: Apr 18, 2009

MononcQc posted:

Yes and no. The question is about the same topic, but the answer you expect isn't the same. It's possible to get the answer to the higher-level question using the API doc, the same way it's possible to get it from the source. It doesn't mean it's desirable, though.

It's like when you want to know "is that TV show good?" and the sperglord in the room gets into a 45 minutes tirade about cylons and their impact on popular culture. You get the answer you wanted, but it's buried in a shitload of information you never asked for nor needed to begin with.

ahem, did you actually compare the two examples posted earlier critically? because when I looked at those to answer the question "what's this useful for?", the tutorial went off on some weird invented wombat creature tangent to talk about state machines in erlang

and the edoc answered the question in 3 sentences: Given a callback module implementing the proper_statem behaviour (i.e. defining an abstract state machine of the system under test), PropEr can generate random symbolic sequences of calls to that system. As a next step, generated symbolic calls are actually performed, while monitoring the system's responses to ensure it behaves as expected. Upon failure, the shrinking mechanism attempts to find a minimal sequence of calls provoking the same error.

i'll admit i'd have never found the edoc page on my own so it's not perfect or anything, but that's mainly because Prop-E, Stat'Em! is a name for a disney movie, not for a source code module

MononcQc posted:

The person or team who produces the code and the javadoc should also provide a simple tutorial, instructions on how to get started, how to install and/or configure the app or library, or point to a place that shows how to. It should tell the user why it was written, what it does, etc.
...
Javadoc is good, but it's still limited in what it can be used for. A tutorial alone helps people start using your app/lib, but they're lost when there isn't more offered to them. There's more than one kind of users, and there should consequently be more than one kind of documentation.

sure, but what about the quality of the documentation? your source code may be covered by tests, you may have a lint-tool to show if apidocs are missing or contradicting the API. what about the code that gets published in various tutorials and guides, is that code covered by tests like the other code? if something breaks a tutorial, ~~when~~ will it get fixed?

# ? Apr 27, 2013 00:32

MononcQc: May 29, 2007

Win8 Hetro Experie posted:

ahem, did you actually compare the two examples posted earlier critically? because when I looked at those to answer the question "what's this useful for?", the tutorial went off on some weird invented wombat creature tangent to talk about state machines in erlang

Near the beginning of the tutorial: "PropEr fsm offers a convenient way to test systems exhibiting a finite state machine behaviour. That is, systems that can be modeled as a finite collection of named states and transitions between them." It then goes on and describes a finite state machine, and writes tests for it. It also lists prerequisite documents to read if you want to be sure to understand everything.

Win8 Hetro Experie posted:

sure, but what about the quality of the documentation? your source code may be covered by tests, you may have a lint-tool to show if apidocs are missing or contradicting the API. what about the code that gets published in various tutorials and guides, is that code covered by tests like the other code? if something breaks a tutorial, ~~when~~ will it get fixed?

Well, documentation is hard. There's no way around it for now. Let's go shopping.

I know I wrote tests for all of LYSE's code, and can still run them (anyone can, it's shipped with the .zip file you download). It actually caught errors in the text when tests would pass with the final snippet but an update was forgotten in the book. They got fixed or added to the errata. Some Haskell book's source content can be scanned, compiled, and tests ran over it (it might have been Real World Haskell, I can't remember). Python has doctests so that the documentation's examples also function as unit tests. Knuth recommended literate programming as a way to do things.

If anything, the difficulty of verifying that code snippets in documentation are executing as planned is a problem with the tools, not with the nature of documentation itself. Tracking changes in tools was likely lovely as hell before decent source control.

Things are far from perfect, and it's absolutely painful to write documentation and then have to update it. Software has bugs, and documentation will similarly have errors in it. It's a bit stupid to pretend otherwise, but it can be improved, I think.

# ? Apr 27, 2013 01:03

Max Facetime: Apr 18, 2009

MononcQc posted:

Near the beginning of the tutorial: "PropEr fsm offers a convenient way to test systems exhibiting a finite state machine behaviour. That is, systems that can be modeled as a finite collection of named states and transitions between them." It then goes on and describes a finite state machine, and writes tests for it. It also lists prerequisite documents to read if you want to be sure to understand everything.

that's so generic it's meaningless. ok, so I could model all of my code as a state machine and use this to test it, but should I? will it be a lot of work and if so, what is my upside? but no, let's talk about this cheese-eating wombat and his trips to the cheese-store I couldn't care less about

MononcQc posted:

Well, documentation is hard. There's no way around it for now. Let's go shopping.

I know I wrote tests for all of LYSE's code, and can still run them (anyone can, it's shipped with the .zip file you download). It actually caught errors in the text when tests would pass with the final snippet but an update was forgotten in the book. They got fixed or added to the errata. Some Haskell book's source content can be scanned, compiled, and tests ran over it (it might have been Real World Haskell, I can't remember). Python has doctests so that the documentation's examples also function as unit tests. Knuth recommended literate programming as a way to do things.

this is cool and I applaud you for keeping your example code working.

MononcQc posted:

If anything, the difficulty of verifying that code snippets in documentation are executing as planned is a problem with the tools, not with the nature of documentation itself. Tracking changes in tools was likely lovely as hell before decent source control.

Things are far from perfect, and it's absolutely painful to write documentation and then have to update it. Software has bugs, and documentation will similarly have errors in it. It's a bit stupid to pretend otherwise, but it can be improved, I think.

the way you create documentation is heavily dependent on the tools that are available for documenting. your documentation is only ever as good as your tools enforce, or better. so what to do help things along?

ewll, you mentioned a .zip of code examples, so here's an idea: people should take their example code snippets and turn them into a new project that depends on the original code. it has to be a different project so the example code doesn't become deprecated or dead, and ideally have a different maintainer too

and if this new project is programmed using literate programming, we'll arrive back where we started: the code is again the documentation

# ? Apr 27, 2013 14:09

tef: May 30, 2004; -> some l-system crap ->

MononcQc posted:

Well, documentation is hard. There's no way around it for now. Let's go shopping.

and,

many professional outlets employ technical writers. programmers are not expected to be good at it.
programming education focuses very little on effective communication,
and for some, the motive for learning to code was to avoid writing things in a human language.

writing effectively, clearly is a similar challenge to writing code. both require practice to refine the skill.
we just don't practice writing docs as much as we do code.

quote:

Python has doctests so that the documentation's examples also function as unit tests. Knuth recommended literate programming as a way to do things.

Python can run the code inside documentation to check it works. they make for lovely unit tests.

Literate Programming as Knuth Recommended is really only something that Knuth has pulled off (tex).

(if you recall the classic rebuttal "tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed ${1}q". )

quote:

If anything, the difficulty of verifying that code snippets in documentation are executing as planned is a problem with the tools, not with the nature of documentation itself. Tracking changes in tools was likely lovely as hell before decent source control.

i dunno, we've had things like pod, and javadoc, and docstrings and a whole slew of things over the years. that isn't to say that the tools can't improve, but they aren't so bad that documentation is significantly harder.

Win8 Hetro Experie posted:

and if this new project is programmed using literate programming, we'll arrive back where we started: the code is again the documentation

there is also a difference between knuth's 'literate programming', and the 'code is the documentation'.

the first is organized into chapters and paragraphs, the second is split into modules and classes.

one has a start, a middle, and an end, the other has an index of every identifier broken down by namespace.

# ? Apr 27, 2013 15:01

tef: May 30, 2004; -> some l-system crap ->

literate programs are organized for the convenience of the programmer, not the compiler :2bong:

# ? Apr 27, 2013 15:06

Max Facetime: Apr 18, 2009

tef posted:

there is also a difference between knuth's 'literate programming', and the 'code is the documentation'.

the first is organized into chapters and paragraphs, the second is split into modules and classes.

one has a start, a middle, and an end, the other has an index of every identifier broken down by namespace.

how well it fits depends on the project

in this case with a documentation project that depends on the fully-fledged implementation project that produces your documentation website when run, it doesn't sound that bad. if the project is showcasing several important features, separately and with each one self-contained, literally programming it sounds like a natural fit

# ? Apr 27, 2013 23:43

trex eaterofcadrs: Jun 17, 2005; My lack of understanding is only exceeded by my lack of concern.

im' totally ok with having to read the source, as long as i can have access to it. at least it doesnt loving lie to my face

# ? Apr 29, 2013 03:49

Gazpacho: Jun 18, 2004; by Fluffdaddy; Slippery Tilde

literate programming has nothing at all to do with documentation as it's understood by API consumers

# ? Apr 29, 2013 04:04

Gazpacho: Jun 18, 2004; by Fluffdaddy; Slippery Tilde

i don't know if i can make that change boss, it would mess up the narrative

# ? Apr 29, 2013 04:30

Gazpacho: Jun 18, 2004; by Fluffdaddy; Slippery Tilde

interrupting a book project for 40 years or whatever to get all of the typesetting JUST RIGHT is an achievement that will go down in sperg history, the only thing i can imagine topping that is if ted nelson ever releases a usable xanadu

# ? Apr 29, 2013 04:38

PrBacterio: Jul 19, 2000

Gazpacho posted:

interrupting a book project for 40 years or whatever to get all of the typesetting JUST RIGHT is an achievement that will go down in sperg history

# ? Apr 29, 2013 05:04

Janitor Prime: Jan 22, 2004; PC LOAD LETTER

What da fuck does that mean; Fun Shoe

Gazpacho posted:

i don't know if i can make that change boss, it would mess up the narrative

gonna use this

# ? Apr 29, 2013 05:16

compuserved: Mar 20, 2006; Nap Ghost

Gazpacho posted:

interrupting a book project for 40 years or whatever to get all of the typesetting JUST RIGHT is an achievement that will go down in sperg history, the only thing i can imagine topping that is if ted nelson ever releases a usable xanadu

compuserved fucked around with this message at 05:04 on Apr 30, 2013

# ? Apr 30, 2013 02:07

PleasingFungus: Oct 10, 2012; idiot asshole bitch who should fuck off

im the digraphs

# ? Apr 30, 2013 03:19

hepatizon: Oct 27, 2010

python makes me mad. let's wrap some, but not all, of our important methods as ugly global functions:

quote:

There are two bits of "Python rationale" that I'd like to explain first.

First of all, I chose len(x) over x.len() for HCI reasons (def
__len__() came much later). There are two intertwined reasons
actually, both HCI:

(a) For some operations, prefix notation just reads better than
postfix -- prefix (and infix!) operations have a long tradition in
mathematics which likes notations where the visuals help the
mathematician thinking about a problem. Compare the easy with which we
rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of
doing the same thing using a raw OO notation.

(b) When I read code that says len(x) I *know* that it is asking for
the length of something. This tells me two things: the result is an
integer, and the argument is some kind of container. To the contrary,
when I read x.len(), I have to already know that x is some kind of
container implementing an interface or inheriting from a class that
has a standard len(). Witness the confusion we occasionally have when
a class that is not implementing a mapping has a get() or keys()
method, or something that isn't a file has a write() method.

Saying the same thing in another way, I see 'len' as a built-in
*operation*. I'd hate to lose that. I can't say for sure whether you
meant that or not, but 'def len(self): ...' certainly sounds like you
want to demote it to an ordinary method. I'm strongly -1 on that.

The second bit of Python rationale I promised to explain is the reason
why I chose special methods to look __special__ and not merely
special. I was anticipating lots of operations that classes might want
to override, some standard (e.g. __add__ or __getitem__), some not so
standard (e.g. pickle's __reduce__ for a long time had no support in C
code at all). I didn't want these special operations to use ordinary
method names, because then pre-existing classes, or classes written by
users without an encyclopedic memory for all the special methods,
would be liable to accidentally define operations they didn't mean to
implement, with possibly disastrous consequences. Ivan Krstić
explained this more concise in his message, which arrived after I'd
written all this up.

--
--Guido van Rossum

hepatizon fucked around with this message at 05:22 on Apr 30, 2013

# ? Apr 30, 2013 05:19

tef: May 30, 2004; -> some l-system crap ->

http://first-website.web.cern.ch/blog/first-url-active-once-more :3:

# ? Apr 30, 2013 12:00

tef: May 30, 2004; -> some l-system crap ->

hepatizon posted:

python makes me mad. let's wrap some, but not all, of our important methods as ugly global functions:

whiny ruby/smalltalk user spotted

# ? Apr 30, 2013 12:00

Nomnom Cookie: Aug 30, 2009

java doesn't have functions because it's properly OO

# ? Apr 30, 2013 12:10

skeevy achievements: Feb 25, 2008; by merry exmarx

hepatizon posted:

python makes me mad. let's wrap some, but not all, of our important methods as ugly global functions:

language purity makes a language easier to learn, not easier to use

that said re prefix notation I don't see how print(myString.trim().upperCase()) is somehow less readable than print(upperCase().trim().myString)

# ? Apr 30, 2013 12:46

Sapozhnik: Jan 2, 2005; Nap Ghost

tef posted:

http://first-website.web.cern.ch/blog/first-url-active-once-more

Rt Clicked > View Source

was not disappointed

# ? Apr 30, 2013 12:48

Sapozhnik: Jan 2, 2005; Nap Ghost

hmm yes it's almost like Java-style OOP is arbitrary and inconsistent trash

Just have explicit multimethods with a special syntax like foo!(bar, baz, qux) and forget all the other cargo cult nonsense. Might be a bit awkward outside of a managed environment if you have multimethod tables interacting with dynamic module loading but eh, I liek to think of myself as more of an ideas guy

# ? Apr 30, 2013 12:51

tef: May 30, 2004; -> some l-system crap ->

Mr Dog posted:

hmm yes it's almost like Java-style OOP is arbitrary and inconsistent trash

Just have explicit multimethods with a special syntax like foo!(bar, baz, qux) and forget all the other cargo cult nonsense. Might be a bit awkward outside of a managed environment if you have multimethod tables interacting with dynamic module loading but eh, I liek to think of myself as more of an ideas guy

learn ocaml :v:

# ? Apr 30, 2013 14:21

Stringent: Dec 22, 2004; image text goes here

ocaml, my caml!

# ? Apr 30, 2013 14:22

Shaggar: Apr 26, 2006

hepatizon posted:

python makes me mad. let's wrap some, but not all, of our important methods as ugly global functions:

don't use python or trust anything from someone named guido

# ? Apr 30, 2013 14:29

double sulk: Jul 2, 2010

shaggar was right

# ? Apr 30, 2013 14:29

Blotto Skorzany: Nov 7, 2008; He's a PSoC, loose and runnin'
came the whisper from each lip
And he's here to do some business with
the bad ADC on his chip
bad ADC on his chiiiiip

Stringent posted:

ocaml, my caml!

# ? Apr 30, 2013 15:12

Blotto Skorzany: Nov 7, 2008; He's a PSoC, loose and runnin'
came the whisper from each lip
And he's here to do some business with
the bad ADC on his chip
bad ADC on his chiiiiip

interviewed a guy yesterday who had "deep knowledge of C" on his resume and couldn't explain what volatile means :/

he also listed common lisp as one of his "core languages" and when asked about it explained that what he actually meant was that he pokes at elisp for his emacs config

# ? Apr 30, 2013 15:14