Register a SA Forums Account here!
JOINING THE SA FORUMS WILL REMOVE THIS BIG AD, THE ANNOYING UNDERLINED ADS, AND STUPID INTERSTITIAL ADS!!!

You can: log in, read the tech support FAQ, or request your lost password. This dumb message (and those ads) will appear on every screen until you register! Get rid of this crap by registering your own SA Forums Account and joining roughly 150,000 Goons, for the one-time price of $9.95! We charge money because it costs us money per month for bills, and since we don't believe in showing ads to our users, we try to make the money back through forum registrations.
 
  • Post
  • Reply
coaxmetal
Oct 21, 2010

I flamed me own dad

Shaggar posted:

yeah he did a more real world example which isn't possible in the other 2 cause they've never been used in the real world.

Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.

Adbot
ADBOT LOVES YOU

tef
May 30, 2004

-> some l-system crap ->

Malcolm XML posted:

wait what. monads are literally a design pattern.

elsewhere. design patterns are a posh name for boilerplate code.

quote:

i think it's only IO and ST that use the bind to implement some sort of ordering but the list monad(plus,zip) is useful even outside of that to model nondeterminism. Also list comprehensions can be generalized to monad comprehension (you need a monadplus instance to allow guards)

they have nothing to do with lazyness and the seq primitive is what allows you to actually enforce strictness in haskell (and in fact some of the monad laws break in the presence of seq)

i'll admit lazyness isn't key, but using monads has been very effective for lazy languages. as you point out too.

quote:

it just turns out that a lot of the common design patterns in a lazy,pure functional language end up being monads. monads are a design pattern with a lovely name and you've probably used one unknowingly via list comprehensions or LINQ

i dunno about design pattern, it's a pretty loaded term, but since we started arguing at cross purposes, i'm not going to stop now.

Shaggar
Apr 26, 2006
theres a difference between simple because that's where the requirements end and simple because that's where the capabilities or common usage of the language end. obviously you could do the same simple if else block in java but that's dumb and boring and the hardcoded values + exclamations would be guaranteed to change once someone actually wants to use it. the java provides an example, thought not the best, on how one might accomplish that.

coaxmetal
Oct 21, 2010

I flamed me own dad

Shaggar posted:

theres a difference between simple because that's where the requirements end and simple because that's where the capabilities or common usage of the language end. obviously you could do the same simple if else block in java but that's dumb and boring and the hardcoded values + exclamations would be guaranteed to change once someone actually wants to use it. the java provides an example, thought not the best, on how one might accomplish that.

but if you needed that flexibility you could add it then, and you would have wasted no time. Whereas if you do that from the start, and don't need it, you wasted lots of time.

tef
May 30, 2004

-> some l-system crap ->

Shaggar posted:

yeah he did a more real world example which isn't possible in the other 2 cause they've never been used in the real world.

i love that you are defending that article because the examples are in java.

Shaggar
Apr 26, 2006

Ronald Raiden posted:

but if you needed that flexibility you could add it then, and you would have wasted no time. Whereas if you do that from the start, and don't need it, you wasted lots of time.

and then you get to go through 2x the testing and release process which is where the bulk of the time is spent.

tef
May 30, 2004

-> some l-system crap ->
yep, gonna need 2x as much testing to deploy fizzbuzz into production *cracks knuckles*

Shaggar
Apr 26, 2006
i guess it wouldn't be surprising that a planger would miss the point: fizzbuzz is worthless and trying to turn it into a real world example makes it more useful

prefect
Sep 11, 2001

No one, Woodhouse.
No one.




Dead Man’s Band
zomg shaggar just called tef a planger

Shaggar
Apr 26, 2006
hes more of a general fadlangist, tbf

double sulk
Jul 2, 2010

i have never seen fewer comments than on the code i'm working on

literally none minus boilerplate from whatever app it is

tef
May 30, 2004

-> some l-system crap ->

prefect posted:

zomg shaggar just called tef a planger

prolog is a p-lang :q:

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

gucci void main posted:

i have never seen fewer comments than on the code i'm working on

literally none minus boilerplate from whatever app it is

~good code documents itself~

Shaggar
Apr 26, 2006

gucci void main posted:

i have never seen fewer comments than on the code i'm working on

literally none minus boilerplate from whatever app it is

i just write self documenting code and then comment the few places complexity or weirdness is unavoidable.

tef
May 30, 2004

-> some l-system crap ->
bad code is documented with a comment explaining what it used to do before someone changed it

tef
May 30, 2004

-> some l-system crap ->
i tend to write terrible undocumented and untested code with comments that explain my frustration or shame.

Condiv
May 7, 2008

Sorry to undo the effort of paying a domestic abuser $10 to own this poster, but I am going to lose my dang mind if I keep seeing multiple posters who appear to be Baloogan.

With love,
a mod


tef posted:

bad code is documented with a comment explaining what it used to do before someone changed it

this is how 90% of my code is documented

GameCube
Nov 21, 2006

// just a quick fix for now, we should do this the right way later

// TODO

// sorry for this hack

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

tef posted:

i tend to write terrible undocumented and untested code with comments that explain my frustration or shame.

same

Werthog 95 posted:

// just a quick fix for now, we should do this the right way later

// TODO

// sorry for this hack

# same

''' I'm so, so sorry '''

Nomnom Cookie
Aug 30, 2009



gucci void main posted:

i have never seen fewer comments than on the code i'm working on

literally none minus boilerplate from whatever app it is

10,000 lines of PHP in one file, implementing a six step file upload process, zero comments

MononcQc
May 29, 2007

when there's a discussion about documentation and all programmers can think of is comments in code, there's a huge problem. Looking at the source should be a last resort for anything ever except modifying the source.

Suspicious Dish
Sep 24, 2011

2020 is the year of linux on the desktop, bro
Fun Shoe
// XXX: FIXME

MononcQc
May 29, 2007

People: "Hi I would like to find my way to the post office. Could you help me?"

Programmers: "Well it's not very hard, the streets are all laid out carefully and well named. You just have to walk around the city kind of randomly and you'll find all the places you need. We don't have time to write maps in here, we have stuff to build."

Nomnom Cookie
Aug 30, 2009



MononcQc posted:

when there's a discussion about documentation and all programmers can think of is comments in code, there's a huge problem. Looking at the source should be a last resort for anything ever except modifying the source.

javadoc is good too

MononcQc
May 29, 2007

Nomnom Cookie posted:

javadoc is good too

JavaDoc is good as long as what you want is a reference manual. If you need anything else than a document that says "here is a list of functions and what they do, get lost idiot", JavaDoc is gonna be a pile of garbage most of the time.

Shaggar
Apr 26, 2006

MononcQc posted:

when there's a discussion about documentation and all programmers can think of is comments in code, there's a huge problem. Looking at the source should be a last resort for anything ever except modifying the source.

you should only look at the source if ur changing the source. in source documentation is what we're talking about.

you should always have api level documentation, but even then that should be straightforward.

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

MononcQc posted:

when there's a discussion about documentation and all programmers can think of is comments in code, there's a huge problem. Looking at the source should be a last resort for anything ever except modifying the source.

someone here posted a real good blog post about that a few weeks ago

they should repost it i m h o

Nomnom Cookie
Aug 30, 2009



MononcQc posted:

JavaDoc is good as long as what you want is a reference manual. If you need anything else than a document that says "here is a list of functions and what they do, get lost idiot", JavaDoc is gonna be a pile of garbage most of the time.

good javadoc tells you what a class does, why it does that, and how it interacts with other classes. thats enough to figure out how to do whatever. long-form documentation always leaves a lot out and chances are what i want to do with the library got left out

double sulk
Jul 2, 2010

PleasingFungus posted:

someone here posted a real good blog post about that a few weeks ago

they should repost it i m h o

it was monocqc :q:

MononcQc
May 29, 2007

Nomnom Cookie posted:

good javadoc tells you what a class does, why it does that, and how it interacts with other classes. thats enough to figure out how to do whatever. long-form documentation always leaves a lot out and chances are what i want to do with the library got left out

Documentation is a text like any other and has a target audience. Reference manuals are especially good for people who know the library rather well and either want to be reminded about a given piece of functionality, or want to add knowledge to what they have already. API descriptions will be similar to that.

If I'm someone entirely new to the product/library/service and I want to figure out how to build my own poo poo with it, I don't necessarily give a crap about how your stupid classes interact, I might just want to know (through guides, examples, tutorials, whatever) how to get started, and if I want to know more, tell me where to find it (i.e. your JavaDoc). I don't care about classes, objects, APIs or whatever, I care about how to get a given piece of functionality. "How do I start a session?" is a different question from "What API do I use to submit encoded credentials?"

Once I have enough information and background knowledge, then reference manuals may make sense.

GameCube
Nov 21, 2006

this last page is reminding me why i need to find a new job

Opinion Haver
Apr 9, 2007

code:
dpSwitch :: Functor col =>
    (forall sf . (a -> col sf -> col (b, sf)))
    -> col (SF b c)
    -> SF (a, col c) (Event d)
    -> (col (SF b c) -> d -> SF a (col c))
    -> SF a (col c)
dpSwitch rf sfs0 sfe0 k = SF {sfTF = tf0}
    where
	tf0 a0 =
	    let bsfs0 = rf a0 sfs0
		sfcs0 = fmap (\(b0, sf0) -> (sfTF sf0) b0) bsfs0
		cs0   = fmap snd sfcs0
	    in
		(case (sfTF sfe0) (a0, cs0) of
		     (sfe, NoEvent)  -> dpSwitchAux (fmap fst sfcs0) sfe
		     (_,   Event d0) -> fst (sfTF (k sfs0 d0) a0),
	         cs0)

	dpSwitchAux sfs (SFArr _ (FDC NoEvent)) = parAux rf sfs
	dpSwitchAux sfs sfe = SF' tf -- False
	    where
		tf dt a =
		    let bsfs  = rf a sfs
			sfcs' = fmap (\(b, sf) -> (sfTF' sf) dt b) bsfs
			cs    = fmap snd sfcs'
		    in
			(case (sfTF' sfe) dt (a, cs) of
			     (sfe', NoEvent) -> dpSwitchAux (fmap fst sfcs')
							    sfe'
			     (_,    Event d) -> fst (sfTF (k (freezeCol sfs dt)
							     d)
							  a),
                         cs)
sigh

uG
Apr 23, 2003

by Ralp
only reason I write docs is because of loving t/pod_coverage.t

DaTroof
Nov 16, 2000

CC LIMERICK CONTEST GRAND CHAMPION
There once was a poster named Troof
Who was getting quite long in the toof

MononcQc posted:

Documentation is a text like any other and has a target audience. Reference manuals are especially good for people who know the library rather well and either want to be reminded about a given piece of functionality, or want to add knowledge to what they have already. API descriptions will be similar to that.

If I'm someone entirely new to the product/library/service and I want to figure out how to build my own poo poo with it, I don't necessarily give a crap about how your stupid classes interact, I might just want to know (through guides, examples, tutorials, whatever) how to get started, and if I want to know more, tell me where to find it (i.e. your JavaDoc). I don't care about classes, objects, APIs or whatever, I care about how to get a given piece of functionality. "How do I start a session?" is a different question from "What API do I use to submit encoded credentials?"

Once I have enough information and background knowledge, then reference manuals may make sense.

Nomnom Cookie
Aug 30, 2009



MononcQc posted:

Documentation is a text like any other and has a target audience. Reference manuals are especially good for people who know the library rather well and either want to be reminded about a given piece of functionality, or want to add knowledge to what they have already. API descriptions will be similar to that.

If I'm someone entirely new to the product/library/service and I want to figure out how to build my own poo poo with it, I don't necessarily give a crap about how your stupid classes interact, I might just want to know (through guides, examples, tutorials, whatever) how to get started, and if I want to know more, tell me where to find it (i.e. your JavaDoc). I don't care about classes, objects, APIs or whatever, I care about how to get a given piece of functionality. "How do I start a session?" is a different question from "What API do I use to submit encoded credentials?"

Once I have enough information and background knowledge, then reference manuals may make sense.

why is the session not starting
why is the session expiring after 2 requests
how do i store sessions in a non-JDBC data store
what if i want to start a session manually instead of relying on the servlets integration

theres a place for getting started docs but at some point it won't be enough. given that documentation is never good enough id rather have good javadoc than a good howto. you can figure out howto from the javadoc but the reverse isnt true

xf86enodev
Mar 27, 2010

dis catte!

Nomnom Cookie posted:

why is the session not starting
why is the session expiring after 2 requests
how do i store sessions in a non-JDBC data store
what if i want to start a session manually instead of relying on the servlets integration

theres a place for getting started docs but at some point it won't be enough. given that documentation is never good enough id rather have good javadoc than a good howto. you can figure out howto from the javadoc but the reverse isnt true

yeah man who cares about docs, we get 24/7 phone support with the enterprise package!

Max Facetime
Apr 18, 2009

MononcQc posted:

If I'm someone entirely new to the product/library/service and I want to figure out how to build my own poo poo with it, I don't necessarily give a crap about how your stupid classes interact, I might just want to know (through guides, examples, tutorials, whatever) how to get started, and if I want to know more, tell me where to find it (i.e. your JavaDoc). I don't care about classes, objects, APIs or whatever, I care about how to get a given piece of functionality. "How do I start a session?" is a different question from "What API do I use to submit encoded credentials?"

Once I have enough information and background knowledge, then reference manuals may make sense.

"how do I start a session?" is the same question as "which part of your api opens sessions and is it straightforward to use?"

if there's javadoc that answers the question then you're done. if not, if you're forced to read online tutorials, getting started guides, code examples and stackoverflow then your answer will be to a slightly different question, unclear but brief, incomplete or missing inconvenient details, any code examples are naturally untested and in general the whole thing is several major versions outdated

reading online guides is like reading code comments except without having the source code for sanity checking

MononcQc
May 29, 2007

Nomnom Cookie posted:

why is the session not starting
why is the session expiring after 2 requests
how do i store sessions in a non-JDBC data store
what if i want to start a session manually instead of relying on the servlets integration

theres a place for getting started docs but at some point it won't be enough. given that documentation is never good enough id rather have good javadoc than a good howto. you can figure out howto from the javadoc but the reverse isnt true

The problem with this "we can only choose one type of documentation" argument is that sooner or later someone comes in with the argument of "we'll just have a nice source, if you really really have to choose!" and then it goes back to the beginning with "but the source is not good enough!" All the questions you are asking in that post are good and at some point you have to point to the java doc, but having more precise documentation doesn't exclude you from having top-level one.

Of course, how much documentation you need is a factor of the complexity inherent in your application. Having only JavaDoc for PostgreSQL would be terrible on every conceivable level. Same with any more serious piece of software, or more complex libraries. JavaDoc for a library that parses useragent strings and has 3 possible entry points is likely going to be enough.

One example that comes to mind is the PropEr library to do property-based testing. Compare the reference manual with the user guide for the same functionality. Even though it has very comprehensive EDoc documentation (equivalent to JavaDoc) and friendly one at that, it doesn't even compare in describing the intent and purpose compared to the example code and the descriptions in the user guide.

My argument here is not that one type of doc is better than the other. It's that having only one or the other sucks a lot, the same way "having clean abstractions" and "having classes with clear names" are not mutually exclusive.

MononcQc fucked around with this message at 23:12 on Apr 26, 2013

MononcQc
May 29, 2007

Win8 Hetro Experie posted:

"how do I start a session?" is the same question as "which part of your api opens sessions and is it straightforward to use?"

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.

Win8 Hetro Experie posted:

if there's javadoc that answers the question then you're done. if not, if you're forced to read online tutorials, getting started guides, code examples and stackoverflow then your answer will be to a slightly different question, unclear but brief, incomplete or missing inconvenient details, any code examples are naturally untested and in general the whole thing is several major versions outdated

reading online guides is like reading code comments except without having the source code for sanity checking

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.

MononcQc fucked around with this message at 23:16 on Apr 26, 2013

Adbot
ADBOT LOVES YOU

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

you absolutely need a system integration guide that can tell someone what components exist and what they do, how they interact with each other, and, most importantly, what the point of the system is and what it provides to the business. this document shouldn't even be that technical aside from "its java" or "this is the name of the api" since the api/implementation details don't matter at that level. Anyone will be able to look at the low level details and figure it out, either through good api design/naming or by digging thru the code. No one, not even the people who are still actively working there, will be able to tell you every business problem the system was designed to solve. That's why you need high level documentation.

bonus points for visio diagrams.

  • 1
  • 2
  • 3
  • 4
  • 5
  • Post
  • Reply