|
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.
|
# ? Apr 26, 2013 18:23 |
|
|
# ? Jun 11, 2024 18:45 |
|
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) 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.
|
# ? Apr 26, 2013 18:32 |
|
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.
|
# ? Apr 26, 2013 18:32 |
|
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.
|
# ? Apr 26, 2013 18:34 |
|
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.
|
# ? Apr 26, 2013 18:36 |
|
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.
|
# ? Apr 26, 2013 19:07 |
|
yep, gonna need 2x as much testing to deploy fizzbuzz into production *cracks knuckles*
|
# ? Apr 26, 2013 19:10 |
|
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
|
# ? Apr 26, 2013 19:11 |
|
zomg shaggar just called tef a planger
|
# ? Apr 26, 2013 19:14 |
|
hes more of a general fadlangist, tbf
|
# ? Apr 26, 2013 19:15 |
i have never seen fewer comments than on the code i'm working on literally none minus boilerplate from whatever app it is
|
|
# ? Apr 26, 2013 19:15 |
|
prefect posted:zomg shaggar just called tef a planger prolog is a p-lang
|
# ? Apr 26, 2013 19:17 |
|
gucci void main posted:i have never seen fewer comments than on the code i'm working on ~good code documents itself~
|
# ? Apr 26, 2013 19:19 |
|
gucci void main posted:i have never seen fewer comments than on the code i'm working on i just write self documenting code and then comment the few places complexity or weirdness is unavoidable.
|
# ? Apr 26, 2013 19:20 |
|
bad code is documented with a comment explaining what it used to do before someone changed it
|
# ? Apr 26, 2013 19:21 |
|
i tend to write terrible undocumented and untested code with comments that explain my frustration or shame.
|
# ? Apr 26, 2013 19:22 |
|
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
|
# ? Apr 26, 2013 19:24 |
|
// just a quick fix for now, we should do this the right way later // TODO // sorry for this hack
|
# ? Apr 26, 2013 19:24 |
|
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 # same ''' I'm so, so sorry '''
|
# ? Apr 26, 2013 19:25 |
|
gucci void main posted:i have never seen fewer comments than on the code i'm working on 10,000 lines of PHP in one file, implementing a six step file upload process, zero comments
|
# ? Apr 26, 2013 19:27 |
|
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.
|
# ? Apr 26, 2013 19:29 |
|
// XXX: FIXME
|
# ? Apr 26, 2013 19:29 |
|
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."
|
# ? Apr 26, 2013 19:34 |
|
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
|
# ? Apr 26, 2013 19:34 |
|
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.
|
# ? Apr 26, 2013 19:35 |
|
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.
|
# ? Apr 26, 2013 19:36 |
|
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
|
# ? Apr 26, 2013 19:36 |
|
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
|
# ? Apr 26, 2013 19:50 |
PleasingFungus posted:someone here posted a real good blog post about that a few weeks ago it was monocqc
|
|
# ? Apr 26, 2013 19:53 |
|
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.
|
# ? Apr 26, 2013 19:58 |
|
this last page is reminding me why i need to find a new job
|
# ? Apr 26, 2013 20:01 |
|
code:
|
# ? Apr 26, 2013 20:05 |
|
only reason I write docs is because of loving t/pod_coverage.t
|
# ? Apr 26, 2013 20:08 |
|
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.
|
# ? Apr 26, 2013 20:12 |
|
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. 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
|
# ? Apr 26, 2013 20:21 |
|
Nomnom Cookie posted:why is the session not starting yeah man who cares about docs, we get 24/7 phone support with the enterprise package!
|
# ? Apr 26, 2013 20:35 |
|
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?" "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
|
# ? Apr 26, 2013 20:36 |
|
Nomnom Cookie posted:why is the session not starting 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 |
# ? Apr 26, 2013 23:10 |
|
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 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 |
# ? Apr 26, 2013 23:11 |
|
|
# ? Jun 11, 2024 18:45 |
|
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.
|
# ? Apr 26, 2013 23:19 |