Slashdot Mirror


How To Get Developers To Document Code

snydeq writes "Poorly documented code? Chances are the problem lies not in your programmers, but in your process, writes Fatal Exception's Neil McAllister. 'Unfortunately, too few developers seem to do a good job of documenting their code. Encouraging them to start can be a difficult challenge — but not an impossible one,' McAllister writes, adding that to establish a culture of documentation managers should favor the carrot before the stick. 'Like most people, programmers respond better to incentives than to mandates. Simple praise can go a long way, but managers may find other ways to reward developers. Are your developers occasionally on-call for weekend support duties or late-night update deployments? Consider giving them a break if they volunteer to pick up some extra documentation burden. Of course, financial incentives work, too.'"

545 comments

  1. How to poke a dead body by alphatel · · Score: 2, Insightful

    It's called doing your job.

    --
    When the foot seeks the place of the head, the line is crossed. Know your place. Keep your place. Be a shoe.
    1. Re:How to poke a dead body by rufty_tufty · · Score: 5, Interesting

      True but like it or not people don't do it. You can bitch that people should do it, but when they don't what then? You could fire them, but IME some of the people who write the best code by other metrics (reliability, bugs fixed, or just taking on a task no-one wants) are poor at documenting it themselves.
      Do you fire people for not documenting code, discipline them? Is it worth fighting the battle if you just need to get the product out/fix the current problems/develop the next thing.
      IME code quality always comes back to bite you, if you write bad code/undocumented then soon enough it will come back and bite you yourself when you come back to maintain/modify. If I don't provide documentation to others then I end up with more support requests so it's worth me doing that balancing act, it's not management's judgement call to make.
      As for dealing with other people undocumented code, that's just a skill you need to have as an engineer, like being fluent in multiple languages many of which won't be your choice. You think I want this tool chain to be written in TCL? Should I then port it to my favourite language (e.g. perl) what if the next poerson to support it prefers python? It's just part of engineering that everyone else's code will look rubbish and undocumented to you. Even when it is documented you'll then think the documentation is overkill.
      Yes it's rubbish, yes TFA makes some suggestions, some might work, some might not, but you can't just say it's your job to document and walk off, in real life we have to actually deal with problems and the reality that it doesn't happen as it should.

      --
      "The weirdest thing about a mind, is that every answer that you find, is the basis of a brand new cliche" -
    2. Re:How to poke a dead body by Anonymous Coward · · Score: 2, Informative

      It's called doing your job.

      And if your job does't measure your comments as part of its "productivity metric"? Like companies that use 'Klocs' to see how much 'work' you've done?

      Commnets aren't included when counting. So, it's quite clear that commenting code isn't part of the job.

    3. Re:How to poke a dead body by Anonymous Coward · · Score: 0, Insightful

      It is their job.

      If they don't do it, fire them.

      If you can't fire them for some reason, give them crap reviews and crap tasks.

      Carrot & stick.

      I've run multiple dev teams. The stick was doing the builds for all the platforms that we supported ... like 10 of them. It took 4+ hrs. I had a histogram posted outside my office with the names of all the devs and usually the person who did the fewest builds got to do the next one. Simple. When someone screwed up in any way, they got to do builds for a week without any credit. Breaking the build on any platform meant you had to do the build for 2 weeks no credit. Breaking the build was terrible since it impacted 20 other people.

      Comments for comment verbosity is worthless. Comments need to say more than what the code already says. I prefer function/method comments more. Explain what the function does for the program and user, not "this is a FFT function" - duh. Say what the input ranges need to be, how exceptions are thrown, if function pointers are used to call it (not easily found in code), etc. Things that are not obvious.

      Oh, and no function should be longer than about 20 lines. If you can't see the entire function inside a single window, it is too complex and needs to be simplified.

      If you think your code is beautiful and it has been a month, you are confused. All non-trivial code is crap and could be improved in some way. Therefore, the goal needs to be to make all your code appear to be trivial.

    4. Re:How to poke a dead body by Moryath · · Score: 5, Insightful

      Indeed. The rise of "metrics for job performance" has caused a lot of pain for many sectors of IT.

      Judging your programmers by "lines of code written"? Great. They'll write a solution with as many redundant lines of code as possible. They won't comment, because commenting doesn't count. Bugfixes will generally involve patch code that means more lines, rather than cleaning up the code itself.

      Judging your IT support by "number of tickets cleared"? Great, you get just what people expect out of those @##$@#$ crapass "phone lines" that bank out of India or Malaysia; they'll do anything to get you off the phone as fast as possible and mark your issue "resolved", whether it is or not. Your in-house guys will have to triage: do we handle 5 "my flash isn't working and I can't watch youtube on company time" issues, or do we handle the issue for one person that's going to take ALL MORNING to resolve but since it's only one ticket, will red-flag us as "not getting enough done" according to The Almighty Metrics.

      The Retardicans have started to try to put this into play in the education field, too - teachers' pay will now be dependent on the grades the kids get and their performance on certain tests. You can - as my mother has - put in 70 hour workweeks, staying after every day to tutor kids who have problems, seeking out specialists to help the couple of kids who actually may wind up diagnosed with a learning disability (example: one in particular can write at an 8th-grade level but can't seem to wrap his head around long division after 6 months of trying), trying to figure out what's with the others only to find out come P/T conference night that they aren't learning because they've internalized their parents' opinion of school as glorified daycare and therefore just don't want to pay attention - but the parents DEMAND that they be passed on to the next grade because it'll hurt Little Dumbass McAsswipe Junior's "self esteem" to be held back a grade. You can do all that and it WON'T MATTER, because the kids with learning disabilities won't be diagnosed for another 4 years, and there are enough Dumbass McAsswipe Juniors in the class to pull "the metric" down.

    5. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      You sound like a fun guy to work with - if that included a carrot.

    6. Re:How to poke a dead body by Eraesr · · Score: 5, Insightful

      Most of the time the problem doesn't lie with the developer. The developer who actively refuses to document is rare. In my experience, the real problem lies in managers not taking documentation seriously. It is caused by developers being under the stress of deadlines with a manager that really needs this piece of software to be finished yesterday. Managers just don't schedule in any time for documentation.

      Another issue the article touches (and I really shouldn't have to say this because of course you have already thoroughly read the entire article. Twice) is that there's the question of when to start documenting, because software and APIs are often subject to change all the time, not in the least because managers keep asking for new or different features.

      Personally, I often enjoy writing technical documentation. If I've written good portions of an API or framework that I'm particularly fond of, because it's all done oh-so-clever, you know, I enjoy committing the inner workings to paper to explain to my colleagues how it works and how it's supposed to be used. Unfortunately, like I said before, there often isn't any time to write good documentation and that's a real shame.

    7. Re:How to poke a dead body by gbjbaanb · · Score: 1, Interesting

      no, you can keep badgering them to do their job properly, with the usual restrictions if they don't.

      For example, what happens if coder A decides he doesn't want to use the company standards to write code, or he decides that writing the stock-keeping module is boring and works on an Android app instead? The same goes for not writing the support documentation to the minimum standard too.

      I find that the process needs to say that no application is accepted as delivered until the minimum docs are supplied along with it. The docs should be enough that someone else can install it (as someone else usually does). Coders who don;t do the work properly get taken off their current code and put back on their old stuff until it's right. That includes the doc part.

      Coders may thing they're some kind of elite, but they have to play according the the rules that are set by the company. If company requires docs, then docs is what they get.

      So, yes, you're right that poor quality code bites you back, but that's still no excuse to allow guys who want to deliver the poor quality code and then let some other maintenance engineer maintain and support it (there are enough places where dev and maintenance are split tasks, this is bad IMHO)

    8. Re:How to poke a dead body by Anonymous Coward · · Score: 1

      I write very little in the way of comments. Really only when for some silly reason I can't break stuff down into stupid simple components and have to do some hairy nested for loop or something.. or have to break convention in some way. The most common compliment I have received as a developer is that my code is easy for another developer to pick up, understand, and maintain. Most comments are a poor solution to badly written code. I've worked on projects that had stiff requirements regarding comments and penalties for not commenting. Invariably the comment loosely describes what a person intended to do during the first pass through of this code but it has since been refactored and updated numerous times and the comments are worthless noise.

    9. Re:How to poke a dead body by LordLucless · · Score: 5, Insightful

      I totally agree.

      You want to know how to make developers document? Give them time to do it. Do not give them another project until the one they've just deployed is documented. Factor in time for documentation when quoting for the time taken to complete a project, and don't treat documentation time as "pad" time that can be consumed by the project when it overruns its overly-optimistic deadline.

      Treat documentation as as valuable as code, and it will get done.

      --
      Just because you're paranoid doesn't mean there isn't an invisible demon about to eat your face
    10. Re:How to poke a dead body by Anonymous Coward · · Score: 4, Interesting

      At my company our process now is built around Design By Contract. Since C++ doesn't have all of the DBC concepts built in as language features, we use comments and macros to define the contract for each class, method or function. The comments include pre conditions, post conditions and the testable restrictions on input parameters and return results (i.e. param x must be between 1 and 10, possible return results are -1,0 or 1). These comments are implemented by macros that do the actual verification.

      We then do rigorous code review--if your methods aren't commented and the macros don't match the comments, your code is rejected. Therefore all of the code in our repository is commented and the quality of the comments are exceptionally good. What's more, all of our code is inherently testable. We also don't mark a module "done" until it has 100% test coverage from our automated test suite.

      So far in the 18 months we've been doing this process, no one has complained of the "burden" of doing the process and everyone has a much clearer understanding of our system design now. And everyone has had at least once experience where the DBC methodology has found what would otherwise have been difficult bugs to find.

      So where we work, comments are part of the code and cannot be omitted. And yes, if we had an engineer who refused to comment he would be fired.

    11. Re:How to poke a dead body by kbg · · Score: 1

      How hard can it be to launch the build? Isn't it just:

      cd project
      build

      And I usually have automatic nightly builds. Then you just check your email in the morning for the results.

    12. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      "When someone screwed up in any way, they got to do builds for a week without any credit."

      This must be a joyful place to work.
      Fire me? Hell, I'd have been out the door before you had even taken the first breath to start the sentence.

    13. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Carrot vs stick isn't just for developers. The only real stick I have as a manager is firing, anything else (assigning shit work, for example) is petty and even more counterproductive than ignoring the problem.

      Carrots, in the form of praise, tangible bonus, etc. are much more effective psychological tools, on everyone from rats in mazes to little children to software developers to golden parachuted CEOs.

    14. Re:How to poke a dead body by rufty_tufty · · Score: 5, Insightful

      It is their job. If they don't do it, fire them. If you can't fire them for some reason, give them crap reviews and crap tasks.

      I envy you that you work somewhere where there is an excess of perfect people that you can do this. In my experience there are some really clever people out there who have some personality flaws, and there are lots of people who stick to the rules and are quite average. Personally I'd rather try and work with flawed brilliant people and accept undocumented but efficient, quick, timely code than get a monkey who follows the rules and produces acceptable code. You may not choose that trade off and that's fine we will probably never agree there...
      Now if you're telling me you can get someone who does everything brilliantly then great, but lots of great engineers are divas so whilst you can try and lead them, to give someone a poor review (when they saved your behind at the last customer demo) because that code they cooked up lacks documentation then I'm once again wondering how on earth I ended up with such an awesome job.
      FWIW I used to have a manager whose approach to people who he thought produced unmanageable/undocumented code was to stick them into a code maintenance/system integration role. It was interesting how quickly you then started complaining about other people's code and documenting both theirs and yours ;-)

      Oh, and no function should be longer than about 20 lines.

      Where's my funny mod points when I need them?

      All non-trivial code is crap and could be improved in some way

      I would say all code is crap and could be improved, the problem is where and for what purpose? Code with too much abstraction is crap, so is code with 1 line per function, so is code with too many things happening on one line, so is code that is too tied to the particular hardware, so is code that ignores what the toolkit libraries can do, so is code that is written in the wrong language for the problem you are solving, so is code that is a complete re-write, so is code that wasn't profiled properly. etc
      Any blanket rule you can make has exceptions and while I am all for coding standards and code reviews rules are there to make you think before you break them, nothing more.

      --
      "The weirdest thing about a mind, is that every answer that you find, is the basis of a brand new cliche" -
    15. Re:How to poke a dead body by JoeMerchant · · Score: 3, Insightful

      Most of the time the problem doesn't lie with the developer. The developer who actively refuses to document is rare. In my experience, the real problem lies in managers not taking documentation seriously. It is caused by developers being under the stress of deadlines with a manager that really needs this piece of software to be finished yesterday. Managers just don't schedule in any time for documentation.

      Roll it up the chain, the Manager's manager doesn't value documentation, they value product, as does the customer. Internal documentation is something with a payoff next quarter, or more often next year. When is the last time you heard of an American business strategy that involved taking more time to do something now so that you could take less time to do something next year?

    16. Re:How to poke a dead body by Anonymous Coward · · Score: 1, Informative

      When I code (which is much rarer these days since OOP and functional has ruined programming for me vs. straightforward linear procedural programming), I used to always write the comments and fill in the code below the comments like it was taught before.

      Thus: /* Do this */

      (code below) /* Do that */

      (code below)

      and so on.

      Yes, many of the lines were self explanatory without the comments, but the point was to be able to read the comments for what the code below does BEFORE EVEN HAVING TO LOOK AT THE CODE. Then, look at the code for changing it or bug-fixing, of course.

      IMHO, elegant and even "self-documenting" code isn't as good. I don't care if the approach seems old school, unless I am programming as a job for a company.

    17. Re:How to poke a dead body by JoeMerchant · · Score: 4, Interesting

      Treat documentation as as valuable as code, and it will get done.

      Who is it valuable to? When is is valuable to them? It is a complicated time-value of resources problem, and while documentation is very valuable when you need it, your time of need is a) uncertain, and b) in the future, both of which steeply discount its value (but not its cost) in the present.

      Decisions are made in the present, and if resources are tight in the present, things of potential value in the future are discounted further.

    18. Re:How to poke a dead body by Penguinisto · · Score: 1

      Damn, that's a waste of effort... we do *continuous* automated builds for each of our projects, something on the order of once every hour. The only time a manual build is kicked off is either to gold it, branch it, or is kicked off from a PM not wanting to wait for the automatic one to trigger before testing an implementation out.

      Oh, and no function should be longer than about 20 lines. If you can't see the entire function inside a single window, it is too complex and needs to be simplified. If you think your code is beautiful and it has been a month, you are confused. All non-trivial code is crap and could be improved in some way. Therefore, the goal needs to be to make all your code appear to be trivial.

      Beautiful philosophy (seriously), but I sincerely hope you're willing to (and occasionally do) put your keyboard where your mouth is. The last thing any dev needs to put up with is a boss who talks the talk, but can't (or won't) walk it himself.

      --
      Quo usque tandem abutere, Nimbus, patientia nostra?
    19. Re:How to poke a dead body by SecurityGuy · · Score: 4, Insightful

      Metrics aren't bad in themselves, but bad metrics are terrible. Lines of code written is a really bad metric.

      I've seen the ticket one happen too many times. Someone will call because n people are having a problem, and ask if the hell desk person wants the info on the other people so they can get fixed, too. Nope. Have them call and open tickets. More tickets with simple, known solutions == more tickets closed quickly.

      And yeah, the same is true of teachers. Teachers *should* be judged on their effectiveness, but the way we do it is often nonsense. Don't ask me to come up with the method, the one thing I DO know is that someone with no experience in the field (me) should not be the one divining metrics to measure them. That said, we've all been through school, and some of us have put kids through school. You know some teachers are better than others, and some are really bad. We do want to find ways to encourage all of them to be better and to get the worst to go do something else. There are also fit issues between teachers and children. The teacher you found to be great for your kid might be average or bad for mine.

    20. Re:How to poke a dead body by swalve · · Score: 0

      Ugh. I absolutely hate the "carrot and a stick" metaphor. Who wants a fucking carrot as a reward? The metaphor is "carrot on a stick" and it originally referred to a manager changing the finish line when an employee got near it, from an old cartoon of a farmer on a mule, who got the mule to work because he hung a carrot on a stick and dangled it in front of the mule to entice it to walk. The mule was so stupid that it never figured out that the carrot kept moving forward along with him.

    21. Re:How to poke a dead body by jsfetzik · · Score: 1

      One big problem I have seen is that developers are never given any sort of training related to documenting. That and standards are seldom in place. So you can tell developers to document stuff, but if they are never shown what to do or how to do it, it just isn't going to get done in a useful way.

    22. Re:How to poke a dead body by defaria · · Score: 1

      Yes you fire them. You tell them they need to do their job and if they refuse to then you fire them. It's called discipline and you accomplish it by having a backbone. If Mr Crackerjack Programmer can't keep a job and feed himself he'll change his tune.

    23. Re:How to poke a dead body by swalve · · Score: 1

      The point of the metrics is to view them at a far enough distance that the individual differences don't matter. If one guy is stuck on a day-long Difficult Problem, the rest of the team can crank through the easy problems even quicker, and at the end of the day, week or month, it all evens out. If you look at the team numbers and everything is equal (all techs catch calls randomly), and you have one tech who has lower numbers, that warrants investigation. Maybe he is just unlucky, or maybe he is a slacker. Same thing with NCLB, sort of. If a cohort of students progresses fine, and then they get with a certain teacher and suddenly their progress slows, it's pretty obvious there is some problem in that classroom. Usually it is the teacher. A classroom full of students is generally going to average out on the bell curve of human potential. If you have a group of students with an unusually high percentage of dumb kids, that blip in the statistics will have shown up in their previous years.

      If I was in charge of NCLB, I'd mandate yearly (or even more often) tests that not only test what a group of kids has learned, but that also tests what they should be learning the next year. The data from the tests can be used to measure teacher performance, but also help to build curricula for the next year. If the kids somehow didn't quite get long division in 4th grade, then the 5th grade teacher needs to pick up there and re-teach what has been missed. Getting the kids from a 4.5 grade level to a 5.6 grade level in one year ought to be a bigger win than getting them from a 5.1 to a 6.0, even though the top number is lower.

    24. Re:How to poke a dead body by Asic+Eng · · Score: 4, Informative

      It's a pity you didn't read the article, because you are one of the people who could benefit from it.

      What happens if your only management tool is badgering? People are going to be frustrated and bored. Their productivity will go down, the quality of their output will be reduced. You'll respond with more badgering and the situation will get worse. You can of course fire them, or they might look for more fun places to work by themselves, but then you are in the worst case scenario with heaps of undocumented code and no access to the people who understand it.

      This is basically unavoidable, because working creatively means - among other things - that you'll have to motivate yourself to do the work. It's not as easy as picking up a shovel and doing the only thing you can do with it (the work there is in the shoveling, though). Unfortunately the energy people have to motivate themselves is not unlimited. The harder a place of work makes it, the less the employees will succeed. Any basic management handbook will tell you that, any research available on the topic will tell you that - but still people prefer to manage by what they think ought to be true, instead of what's known to be true.

    25. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      when the project deadline is set at half of the time required to properly design and implement the project and there is no stop date for new features, where does time to write documentation come from? the reasonable deadline fairy?

    26. Re:How to poke a dead body by txsable · · Score: 2

      I worked in health care IT at a hospital system for about 8 years. About 4 years after I started, the hospital administration implemented "performance metrics" across the entire system, from nurses to physical plant to...yea, IT services. Anyone want to guess what "metric" they were going to use to measure IT performance? Was it number of tickets completed? number of PCs serviced or printers replaced in a month? No..someone decided that the best metric for measuring IT was...PATIENT DISCHARGES. The number of patients (which the IT staff stayed as far from as possible) discharged by the hospital. Not only was it a statistic we had absolutely no control over, but was it totally irrelevant to our (IT services) business line. Fortunately, we had a competent VP/CIO who stood up for his IT staff and put a stop to that ludicrousness but for about two months we had to suffer from "low performance ratings" while the powers that be figured out how to measure our actual service to the hospital system.

    27. Re:How to poke a dead body by Sectoid_Dev · · Score: 3, Insightful

      If 20 lines of codes is your boundary of complexity, then programming is not for you. Breaking code into screen sized 'called once' sections adds unnecessary complexity, especially if you validate your inputs(as all good programmers should).
      Some things are just inheritently complex and the most efficient implementation might be rather abstract and not obvious at first. If you can't understand it at a first pass, the problem isn't necessarily the code.

    28. Re:How to poke a dead body by Anonymous Coward · · Score: 1

      In what seems like another life, I was the lead tech on a for-profit team in a support call center. Unlike the warranty support teams, my team was encouraged to stay on the phone as long as possible, while closing as many tickets as possible. For the suits, the only metric that mattered was the "first call closed rate", as this metric was directly related to the satisfaction metric collected by a separate QA department.

      We were encouraged to spend as much time as necessary in order to resolve the issue, and we were encouraged to support anything that the caller requested. As a result of these goals, my team was the best equipped of any department in the company. We had any hardware that we asked for, any software, peripheral device, and unrestricted internet access. The company gladly gave these things to us and consistently asked "Anything else?" For $1.99 per minute, they were more than willing to keep us happy.

      Those were the days... Until someone higher up the food chain wasn't satisfied with the profits and decided to move the entire operation to India. After the move, the department lasted 3 months before being shut down.

      Occasionally, the metrics make sense. There are some suits that "get it"

    29. Re:How to poke a dead body by Anonymous Coward · · Score: 4, Insightful

      Unruly behavior like refusing to follow coding standards can be a sign of a problem employee that you have to let go, but it can also be a sign that all of your developers perceive your policies to be detrimental to both them and the business, and this person is the only employee you've got that cares more about the company and his craft than about his immediate bosses' sensibilities. That sort of courage could easily derive from the fact that perhaps this person is the only person who is in demand enough that he could easily find a job elsewhere. Managing by badgering, lashing and threats of firerings is a great way to lose the respect of everyone working for you. That's when suddenly productivity drops and bugs go up for no apparent reason.

      If you are a leader, and if people thought that a policy was god-awful, and then suddenly they all stop talking about it ever to you, that probably means that they have given up on your organization due to your leadership, and now they are just going in from 9-5, doing whatever you say to keep you happy, while not showing any initiative to bend your policies in the interest of the business - they are probably also looking for a different job at the same time.

      An employee who does just exactly what you say is the worst possible kind of disaster waiting to happen. You absolutely need your employees to question you. "oh, you need me to quickly finish this piece of code because minor customer X wants it now? Well, I happen to know that that same routine will have lots of bugs if not done carefully, and we are going to use it also to give to our major customer Y, to whose interests it is vital that this code work perfectly, but I won't question you by mentioning that and instead give you what you asked for." It's called malicious compliance. If you insist that employees ignore the good of the business and follow your orders to the letters instead, then watch out, you may eventually break some of them to give you what you ask for, and you won't like it.

    30. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Who is it valuable to? When is is valuable to them?

      It is valuable to you, the programmer, and your entire team.

      When one guy leaves (the company or the team), or is on vacation, and you have to look over a part of the code that you normally didn't work with, then you'll find it helpful.

      It is self-interest for the team to document code, but you never know when/if you'll have to go into a part that you're unfamiliar with.

    31. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Tough to say, i mean.. Properly named methods and variable names will document 99% of the code for you.

    32. Re:How to poke a dead body by Imagix · · Score: 1

      The danger in your method is when (code below) gets changed, but the comment does not. As a result, the comment says something different than the code. That's where the advantage of "self-documenting" code comes in. When you change the code (to also self-documenting code), you don't run the risk of saying two different things.

    33. Re:How to poke a dead body by jeremyp · · Score: 1

      There's nothing wrong with the carrot and stick metaphor. In the metaphor, the reward is represented by the carrot, the punishment is represented by the stick and the person is represented by the (implied) donkey, that likes eating carrots and dislikes being beaten with a stick. It has nothing to do with the carrot on a stick metaphor.

      --
      All I want is a secure system where it's easy to do anything I want. Is that too much to ask ~~ Randall Munroe
    34. Re:How to poke a dead body by umghhh · · Score: 2

      I was convinced over the years of development, test, integration & maintenance jobs that comments are of utmost importance. When I had to write a few new modules all but myself I did indeed produced a series of descriptions in form of short module description, some comments to non obvious parts of code when after return another piece of code were to be executed when... and if... Well all this went out of window when I started to work with 5o other developers with a feeling taht all of them tried to work on the same piece of code that I was just to write. Inevitably the comments that I put for module description or TODOs were completely ignored. In a while I learned that making comments in such env. is a double. waste of time: first by writing and then by encountering my own not more valid comments that have not been updated by others. From this I learned that my comments are obviously not as desired as I thought and that I would do better to invest time in reading and analyzing code than reading comments.

    35. Re:How to poke a dead body by Tom · · Score: 4, Interesting

      Who is it valuable to?

      It's an investment into the future. If you need to pick this project up again one, two or five years down the road, and do any non-trivial changes to it, good (and that means correct, short and to the point, not extensive and theoretical) documentation will save you valuable time.

      If it's throwaway code, don't waste time and effort on documentation. If you plan to use it for some time, chances are very high it will need fixes, updates and changes, and documentation will make those a lot easier, faster and cheaper.

      Decisions are made in the present, and if resources are tight in the present, things of potential value in the future are discounted further.

      Yes. I've been trying for years to tell managers that the only reason that resources are so tight in the present is because they've been thinking that way in the past.

      --
      Assorted stuff I do sometimes: Lemuria.org
    36. Re:How to poke a dead body by Surt · · Score: 2

      It seems to me that if your only management tool is badgering, your core problem does not lie with your development team.

      --
      "Who is the Journal of Quantum Physics going to believe?" --Stephen Hawking
    37. Re:How to poke a dead body by Golddess · · Score: 1

      Ugh. I absolutely hate the "carrot and a stick" metaphor. Who wants a fucking carrot as a reward?

      Wait, so you think that "the carrot or the stick" is metaphorically referring to a literal carrot?

      The metaphor is "carrot on a stick"

      Except that that is not a metaphor for "rewarding good behavior vs punishing bad behavior".

      --
      "I'm not sure I like the fugnutish tone you used in your post!" -RogL (608926)-
    38. Re:How to poke a dead body by ios+and+web+coder · · Score: 1

      Good points. As a manager of a C++ shop, and as a person that writes A LOT of Web and iOS stuff, I have quite a bit at stake here. My team (the job that pays my salary) doesn't do enough documentation. That's not their fault, that's mine. I haven't put enough priority on docs, and I haven't given documenting the schedule padding it deserves. That being said, I need to come up with creative ways to encourage documentation. Good process helps. A set of rules, heuristics and templates, spelling out decent coding, is helpful. It is, indeed, possible to write "self-documenting" code, but most folks won't do it, and that fox may not be worth the chase. The "sweet spot" seems to be a combination of decent coding practices, consistent style, and small, concise comments, sprinkled throughout the code. Another way is Doxygen. It works marvelously well, and I use it to create the API docs for my Web and iOS stuff (the stuff that doesn't pay my salary). As my Web stuff is public domain and open-source, it needs documentation, quite badly. I have used Doxygen to produce some truly extensive stuff. However, Doxygen produces only technical/detailed docs. We still need the "big picture" documentation and the structural stuff. That needs to be written separately. By a good tech writer. Many engineers are terrible (I mean God-awful) tech writers. In many cases (including docs that I have written), the documentation is actually WORSE than no documentation. I have written a huge amount of documentation that no one reads, because my information architecture sucks, and because I am the epitome of "prolix." I am in the process of re-evaluating a lot of my documentation, and seeing if I can get other folks, better at writing, to help out. 20 line functions? Sure, I'm sure that exists...somewhere. I've been writing code for about 30 years, in dozens of languages from hex machine code to PHP (with the lions' share being C++), and I've yet to see anything outside of an academic context follow rules like that. I once purchased a set of style guides, written by a company called Taligent. Remember Taligent? The little company that couldn't? Their style guides and coding process was a Stalinistic nightmare. I strongly suspect that had a lot to do with their problems actually producing anything more than rhetoric. My own experience is that most functions fall within the 50-200-line area, with considerable variation. If you do decent Doxygen commenting, the comments can be over 30 lines. Also, performance is a huge consideration. I run a C++ shop, and we use C++ because it screams like a bat out of hell. If written properly. If written poorly, it is quite possible to write code that screams like a wounded brontosaurus. Many performance bottlenecks come from context switching, so long stack frames can be a problem. It may be necessary to write a large static function, in order to provide decent performance. I find "hard and fast" rules to be inapplicable when you are trying to squeeze performance from your code. Threading and cache optimization are changing the way we write code. In many ways, we are starting to write code that looks a lot like what I used to see when I wrote device drivers, 25 years ago. Just my experience in this are. Take it for what it's worth.

      --

      "For every complex problem there is an answer that is clear, simple, and wrong."

      -H. L. Mencken

    39. Re:How to poke a dead body by ios+and+web+coder · · Score: 1

      Damn. I need to learn more about /. formatting. Sorry about the "wall of text."

      --

      "For every complex problem there is an answer that is clear, simple, and wrong."

      -H. L. Mencken

    40. Re:How to poke a dead body by Surt · · Score: 1

      Yep, if your productivity metrics don't measure the goal you care about, your problem does not lie with your development team.

      --
      "Who is the Journal of Quantum Physics going to believe?" --Stephen Hawking
    41. Re:How to poke a dead body by Surt · · Score: 1

      Indeed, documentation is not inherently valuable. I believe it was the premise of both the article and the argument, though, that in the particular context it was.

      --
      "Who is the Journal of Quantum Physics going to believe?" --Stephen Hawking
    42. Re:How to poke a dead body by JoeMerchant · · Score: 2

      Yes. I've been trying for years to tell managers that the only reason that resources are so tight in the present is because they've been thinking that way in the past.

      It's a valid point, but remember you are assessing with hindsight. I have actually lived through two catastrophic crashes where any effort expended for returns beyond the 3 month horizon would literally have been wasted. It is an unfortunate situation, and to be avoided if possible, but these things do happen.

      What really bothers me is when the true horizon is 3+ years, but management continues to act like it is 3 weeks.

    43. Re:How to poke a dead body by tlhIngan · · Score: 1

      If it's throwaway code, don't waste time and effort on documentation. If you plan to use it for some time, chances are very high it will need fixes, updates and changes, and documentation will make those a lot easier, faster and cheaper.

      Throwaway code has a nasty habit of becoming production code, unfortunately. Even the one-off utility written to convert some data input file into something usable elsewhere has a nasty habit of suddenly being pushed into production.

      It's an unfortunate reality in life - but really it should all be documented. Even exercise code where you're trying to figure out how to use an API, because someone may ask and you may end up providing code to show them how. Or a year later re-read it trying to refresh your memory on the API.

    44. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      I know you're trolling but I can't help it. RTFA. It's not your job to document code, and that's why it doesn't get done.

      I've yet to see or hear of an organization that considers a task complete when the programmer documentation is finished. Tickets are usually bugs/features that are done when a QA department says it works the way they expect. That has absolutely nothing to do with documentation.

      That's why you don't get documentation.

    45. Re:How to poke a dead body by V+for+Vendetta · · Score: 1

      Metrics aren't bad in themselves, but bad metrics are terrible.

      Metrics are bad, because there always will be at least one person who tries to gamble the system. So the manager needs to put some effort into finding out if and how people try to gamble the system. That's a lot wasted time the manager could use to do important stuff. Or the manager doesn't care about gambling the metrics system ... which leads either to honest devs becoming demotivated and leaving the company or every dev starting to gamble the system. That's because we're humans

      Metrics are good when used for measuring (the work of) machines.

    46. Re:How to poke a dead body by geoffrobinson · · Score: 1

      Amen to this.

      --
      Except for ending slavery, the Nazis, communism, & securing American independence, war has never solved anything.
    47. Re:How to poke a dead body by radtea · · Score: 1

      Metrics aren't bad in themselves, but bad metrics are terrible.

      But good metrics are really hard to come by. For call centers "solving the caller's problem" is the only reasonable metric, but there's no way to measure it. The worst metric I've ever heard of was at a call center where people were penalized for letting calls go over 12 minutes. Predictably (but quite unexpectedly to the morons who imposed the metric) people would do ANYTHING in minute-eleven to get the caller off the line: lie to them, "accidentally" hang up on them, pretend to no longer be able to hear them ("Hello? Are you still there sir?")

      --
      Blasphemy is a human right. Blasphemophobia kills.
    48. Re:How to poke a dead body by gbjbaanb · · Score: 2

      rubbish.

      You're basically saying that the creative people should be given as much free rein as they like because they won't do what they're supposed to anyway, and you'll annoy them if you try,

      Heaps of undocumented code is a problem. That the only doc is in the heads of the developer is truly undesirable because the dev who doesn't document doesn't tend to communicate in other ways when needed, and also because you're expecting that dev to be the only point of contact for all the code he's ever written. That'll annoy him when he starts getting hassled constantly for the knowledge only he holds.

      So its a management responsibility to ensure that this sorry state of affairs doesn't occur, and that his team works in a professional manner. That means the work paid for by the company doesn't stop when the code compiles successfully. If badgering doesn't work (and I doubt it will, but its a good step before you try more formal methods, and badgering doesn't have to be constant nagging - it can simply be a reminder when code is delivered that the dev has "accidentally forgotten" to include the docs too. I meant the same kind of badgering you get when you submit code for code review).

      In the end, the whole product needs to be developed: binaries, installation, support, maintenance, training - all these are part of what you need to do in a professional environment. Some will be done by others (eg. the user guide is sometimes written by technical authors depending on the size of the company - but even then, the dev will be explaining how it works to the tech author/BA/PM so the doc *can* be written), but some will be done by the dev and that's just part of the job.

      If you don't want to do that kind of job, you'll have to start your own company and work for yourself I guess.

    49. Re:How to poke a dead body by radtea · · Score: 1

      Most of the time the problem doesn't lie with the developer. The developer who actively refuses to document is rare.

      I've worked with developers who simply won't document their code. They understand the importance of it, but they aren't able to express their intent in a meaningful and useful way. I've seen them try and fail.

      My solution was to separate the documentation function from the development function, and I'd argue this is worth considering as a development practice. It has several advantages: 1) people who like to document migrate to documentation tasks 2) documentation gets written 3) documenting someone else's code is a great way to understand it and 4) if code can't be documented by someone else it probably has other problems too.

      The document writers need to have some interaction with the code writers, and everyone needs to be writing some code, so no one is 100% documentation. This is a software engineering task, not a technical writing task. The document writers tend to be more junior people, although I've done a fair bit of documentation myself and senior people were encouraged to document other people's code as a break from head-down development.

      I've only experimented with this approach in one relatively small team, but it dealt with a major headache and I'd definitely consider doing it again if I were running a larger team with documentation issues (my current team, bless them, is more meticulous about documentation than I am.)

      --
      Blasphemy is a human right. Blasphemophobia kills.
    50. Re:How to poke a dead body by Tom · · Score: 1

      Throwaway code has a nasty habit of becoming production code, unfortunately.

      Yes, of course. I forgot that problem. That's also a management problem: They tell you they want a quick hack that's just for this one problem. Then two weeks later in a meeting with their bosses, they try to score points by mentioning that they already have working code to solve a similar problem and it would be easy to use it to solve that other problem, too...

      Again, that's not a coding issue, it's a management issue. I'm great at hacks, and I also treasure quality code - and I know that the two are different animals. If only managers also understood that the spare tire is for getting you to the next garage so you can install a proper one, and not for driving across the country.

      Is it really that difficult, just because it's software?

      --
      Assorted stuff I do sometimes: Lemuria.org
    51. Re:How to poke a dead body by gstrickler · · Score: 1

      I agree that the pressure of deadlines and unrealistic scheduling are part of the problem. However, functional documentation of code should be written before the code. If you aren't clear what it is you're intending to accomplish, you shouldn't be writing code yet. And if you do know what you intend to accomplish, what the input and output (e.g. API) should look like (or a rough draft of it), then that should be documented at the start of the procedure/method before you've written a single line of code. Failure to document before you code is a developer failure, not a management failure. Failure to set and enforce policies supporting such practices is a management failure.

      Some things may change as you write it and find that you need more information, or that there is a better way, etc. Because of this, the documentation may need to be updated as you code, or after you finish, but that doesn't change the fact that the preliminary documentation should be written before the code. Management can implement policies that require approval of documentation before coding begins, and in extreme cases that may be necessary, but that's micromanaging and should be avoided and used only as a last resort before terminating a developer who isn't documenting his/her code (see my recommended practices below).

      Where management and scheduling frequently fail is in not allowing time to update the documentation after the code is written, and not having a second developer and/or a qualified QA person read the documentation to determine if it accurately describes the purpose/intent of the procedure/method, the input/output, and the function/operation of the procedure/method. If the documentation and code don't match, then one or both must be changed so they do match.

      Recommended practices: I have found the following to be the most effective way to get developers to document their code:

      1. Have a written policy that functional documentation including the purpose/intent of the procedure/method, expect input & output, and a brief narrative describing the operation must be written before coding. Until someone has repeatedly violated this (as evidenced by lack of documentation in finished or partially finished code), there is no requirement to verify or approve the documentation before coding.

      2. Do not require detailed documentation of every line or loop. Require documenting the basic flow/intent, and documenting any direct use of hardware, use of obscure libraries/functions, or "clever tricks"/shortcuts.

      3. Have a written policy that preliminary documentation must be complete before submitting the project to QA and that all documentation must be complete and up-to-date before it can pass QA.

      4a. Have someone other than the person who wrote the code perform unit testing/QA.

      4b. Have someone other than the person who wrote the code review the documentation. Many developers do not communicate clearly, so clarifications may be necessary. If your QA dept doesn't have people qualified to validate the documentation, or doesn't have access to view the source code, have another developer verify the documentation is complete and matches the code before it can pass unit testing/QA. Unit testing/QA and documentation review may occur concurrently.

      5. Make developers maintain some significant portions of code they wrote at least 6 months prior, and make them maintain some significant portion of code that other developers wrote. Having new developers study/maintain code written by more experienced developers is a good practice to ensure that documentation is clear and complete, and shows the value of good documentation. This step alone should make the value of good functional documentation evident to each developer. When you have trouble understanding code you (or another developer wrote) 6+ months ago, the value of good/bad/insufficient documentation will be obvious.

      6. Take corrective action with developers who fail to follow your documentation policies and guidelines. This may b

      --
      make imaginary.friends COUNT=100 VISIBLE=false
    52. Re:How to poke a dead body by Tom · · Score: 1

      It's a valid point, but remember you are assessing with hindsight.

      Actually, no. In many cases I've been telling that in future tense.

      I have actually lived through two catastrophic crashes where any effort expended for returns beyond the 3 month horizon would literally have been wasted. It is an unfortunate situation, and to be avoided if possible, but these things do happen.

      Yes, they do. About 5% of the time that management claims that the company is in an emergency situation. It is most obvious when management and the legal system clash. I happen to know this in detail regarding the word "emergency". Management very easily declares an emergency. Basically, everytime someone's pants are on fire. The legal definition of a company emergency, however (important for things like bypassing certain employee protection laws, such as those regulating overtime) is much, much, much more narrow. Basically, lives must be in danger or the company must be in present and provable danger of going bancrupt.

      Almost no "emergency" declared by management would survive a legal inquiry. The term is easily thrown around to cause fear amongst employees. Unless you see the CEO walking around with a lawyer at his side and checking for the next flight into a country without an extradition treaty, you should take it with a grain of salt.

      --
      Assorted stuff I do sometimes: Lemuria.org
    53. Re:How to poke a dead body by SecurityGuy · · Score: 1

      Nah, I disagree. Metrics are useful when you're measuring work where you can quantifiably distinguish good work from bad. Yes, yes, yes, that's a hard thing to do. Solving that problem should be one reason we pay managers well. Done properly, it's actually a hard job. Done poorly, you're just filling out TPS reports to fill a filing cabinet.

      I've worked with top developers and ones who'd struggle with Hello World. You're saying there's no way we can actually measure a difference between those people. It's simply not true. If you give developer A an easy task and developer B a complex one, and B solves the problem with a defect-free solution in a month while developer A putters around with it for a year, you can't find a way to make a number that says B good, A bad?

      Of course people will game the system. The thing is, if you can make your numbers better without accomplishing my REAL goal, I've set up the system wrong.

      It may not be worth doing, though. Measuring costs something, both in money, productivity, and potentially demotivating your staff, who actually want to do something, not spend their time being measured. So there's two things we tend to do badly: choose the right thing to measure, and understand when it's not cost effective to measure at all.

    54. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      If I had to read your code I would hunt you down and set you on fire.

      That adds clutter to the code and shows you don't really know how to code.

      Comments give you a basic contract and explain anything out of the ordinary. Everything else is noise that takes away from the readability of the code.

    55. Re:How to poke a dead body by Slashdot+Parent · · Score: 1

      Breaking code into screen sized 'called once' sections adds unnecessary complexity, especially if you validate your inputs(as all good programmers should).

      I don't consider boiler-plate code to really be code. It's more like wallpaper. A lot of languages have facilities that allow you to skip or condense it or move it (sort of like AspectJ allows you to separate out cross-cutting concerns like trace-level logging, etc.).

      Some things are just inheritently complex and the most efficient implementation might be rather abstract and not obvious at first.

      I'm having a difficult time coming up with a situation where that is true. The job of a good architect is to take a complex system and model it so that it makes sense. If a developer who is experienced in the tools/languages that you have used for implementation, and is familiar with the project's requirements, can't look at your code and understand what is going on within a few minutes, your system was not architected very well.

      Additionally, if the logic of a section of code would leave an experienced dev scratching his or her head, then the problem is the code (unless the code was optimized due to an actually-experienced performance problem). If you write some code that is difficult to read, it's not because you are brilliant. Any idiot can spew out complicated code. Brilliance is taking something complicated and making it straightforward.

      Perhaps there is a situation where this is not true, but I have never encountered such a situation. My experience is that code complexity and developer acumen are inversely related.

      --
      They don't grade fathers, but if your daughter's a stripper, you fucked up. --Chris Rock
    56. Re:How to poke a dead body by s73v3r · · Score: 1

      I would say 20 lines is an admirable goal, and development should proceed trying to keep that in mind. However, there are situations where that's just not possible, at least not in a clean, well written, and most importantly, fast, manner. These should be recognized, and accepted when they happen.

      Code review can be good at determining whether the situation was that a long method was necessary, or whether the dev was being lazy.

    57. Re:How to poke a dead body by s73v3r · · Score: 1

      Metrics are bad, because there always will be at least one person who tries to gamble the system.

      This can be mitigated to some extent by using a variety of metrics that measure different things. And, most importantly, not using metrics as the be all, end all of performance review. Use them as a small bit, but not the whole thing.

    58. Re:How to poke a dead body by shutdown+-p+now · · Score: 1

      By the way, if you use VC++, it has a bunch of language extensions that basically amount to a limited form of DbC - null checks, range checks etc - with a static verifier. Those can be wrapped into macros for portable code.

    59. Re:How to poke a dead body by psmears · · Score: 1

      The metaphor is "carrot on a stick"

      Do you have any evidence to back up that assertion?

    60. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Give them time to do it.

      In what IT reality do developers have no say in estimating the size of a project?

      I see lots of developers pay lip service to documentation like this, but they continually:
      1) Underestimate the work required for EVERY system, EVERY time, because they assume that everything they haven't actually tried to do yet is super simple and will only take them a day or two;
      2) Blame management for their poor estimates leaving them with a rush job at the end of the project;

      Stop providing unrealistic lowball estimates, and you'll suddenly find plenty of time for documentation and unit testing and all the other things devs sit there and nod in agreement to, and then complain that "management never lets us do it."

    61. Re:How to poke a dead body by obarel · · Score: 1

      There's also a risk that someone would introduce a bug while keeping the documentation correct. So what? We live in a dangerous world.

      Comments can be useful, and there is no need to avoid them just because they could be wrong. If the code is wrong, you need to know what it's supposed to do (and why) before you can decide that it's wrong. That's where comments can make your life easier.

    62. Re:How to poke a dead body by benhattman · · Score: 1

      Metrics aren't bad in themselves, but bad metrics are terrible.

      I don't know. All metrics have a dehumanizing effect; even the appropriate ones. I mean, as a factory you definitely want a metric of "how many widgets can we produce per month". That's totally appropriate. But, it's not a long step from the metric to viewing the humans on the floor as factory worker-bees, whose only value is in how well they fulfill that metric. It's even worse when the metric spans multiple cities or states or continents. At that point, you can't even look down at a single factory floor to see the humans down there. The people in Foxconn or wherever are little more than their metrics to the rest of the world.

    63. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Well, I think the estimates for the initial implementation are often quite close.
      However often people completely forget or vastly underestimate the time for writing test cases/testing/bug fixing, which I've not yet seen fall under the time needed for the implementation.
      Time for refactoring/code cleanup is calculated in even more rarely and for inherited or old code can easily reach similar levels.

    64. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      So so true. Most people who spout dogma like "never more than 20 lines" have never actually done the research to see if this is beneficial or not. Steve McConnell did the research and on pages 173-174 of his epic "Code Complete, 2nd Edition" cites 7 independent studies that show the routines should be allowed up to 200 lines in order to maximize coherance while minimizing errors.

    65. Re:How to poke a dead body by Yunzil · · Score: 1

      Oh, and no function should be longer than about 20 lines. If you can't see the entire function inside a single window, it is too complex and needs to be simplified.

      It must be awesome, living in Idealistan.

    66. Re:How to poke a dead body by Nodlehs · · Score: 1

      Where is my mod points when I need them? I have read Code Complete and it is well worth buying or borrowing from the library.

    67. Re:How to poke a dead body by aardvarkjoe · · Score: 1

      The product I work on has been in development for about fifteen years now. One of the first things that I learned when getting started was the the comments are your last resort when you're trying to read some code. Trusting that the comments actually match what the code actually does is a recipe for disaster.

      There are a couple factors that contributed to this. One of them is that some of the original developers were the type that would write things like this:

      /*
      **
      ** Increase byte count by 17.
      **
      */
      byteCount += 17;

      Of course, they would completely neglect to document why they were incrementing the byte count in the first place. As time went on, other developers would change the code and not bother to update the (worthless) comments.

      I'm in agreement that the "what" of your code ought to be self-documenting. Repeating it in your comments is redundant and makes it harder to read (or keep updated) the important comments -- the ones that say "why."

      --

      How can we continue to believe in a just universe and freedom to eat crackers if we have no ale?
    68. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      I rather count inner loops than lines of code. You certainly can have some long trivial structures like validation code.

      But every time I see this common phenomenom:

      for (i=1;ilength;i++) { ...
          for (j=1;jlength2;j++) { ...
              for (k=1;klength3;k++) { ...

      My heart cries out loud: "Oh why,why,why,why,why,why?! You bastard!".

    69. Re:How to poke a dead body by Anonymous Coward · · Score: 1

      BS.

      Breaking it into called once sections/methods (without checking the incoming parameters in the small, only called from one place code) is a fantastic documentation technique. Try it on any non-trivial algorithm in almost any language and you'll find it really adds to the code.

      Mind you, 20 lines is a totally bogus number; it depends upon context (problem, language, etc).

    70. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Our boss doesn't see my job as code to X standard, it's done when it's done. His idea is set a deadline (seemingly randomly) then interrupt constantly with other things that must be done NOW. The project MUST be finished by the deadline or you aren't doing your job. How readable our code is doesn't matter to our manager, only getting as many finished projects as possible out of us in the least amount of time. He's a production manager turned project manager who never learned the difference. I doubt our situation is unique.

    71. Re:How to poke a dead body by swalve · · Score: 1

      Some guy on the usenet agreeing with you is not evidence. My evidence is: it's a stupid metaphor. "Carrot" is not metaphorically a reward to anyone but mules and Bugs Bunny. "on a stick" paints a clear picture. "and/or a stick" is muddy. The stick isn't a particularly vivid punishment metaphor, nor is a carrot a memorable reward. Real metaphors tend to be more descriptive than the reality they try to describe. This one is not. Since it uses the same imagery as the "on a stick" metaphor, it follows that someone screwed up the metaphor and it stuck. This whole argument is a great metaphor for management, by the way. Screwing up concepts and treating employees like children or mules. Either way, anyone who uses either one is a moron.

    72. Re:How to poke a dead body by Thing+1 · · Score: 1

      It seems to me that if your only management tool is badgering, your core problem does not lie with your development team.

      Yes, exactly; you need some mushrooms, and the occasional snake, as well.

      (I love that one of the comments there is "I love the ending of this song" :P )

      --
      I feel fantastic, and I'm still alive.
    73. Re:How to poke a dead body by Thing+1 · · Score: 1

      It's called malicious compliance. If you insist that employees ignore the good of the business and follow your orders to the letters instead, then watch out, you may eventually break some of them to give you what you ask for, and you won't like it.

      Exactly. And, your incompetence will ultimately be called out. (The generic "you" that you referred to, that is.) (Unfortunately, it likely won't be until you've gotten rid of ("broken") several far-more-competent-than-you developers...)

      --
      I feel fantastic, and I'm still alive.
    74. Re:How to poke a dead body by Thing+1 · · Score: 1

      Some guy on the usenet agreeing with you is not evidence. My evidence is: it's a stupid metaphor. "Carrot" is not metaphorically a reward to anyone but mules and Bugs Bunny. "on a stick" paints a clear picture. "and/or a stick" is muddy. The stick isn't a particularly vivid punishment metaphor, nor is a carrot a memorable reward. Real metaphors tend to be more descriptive than the reality they try to describe. This one is not. Since it uses the same imagery as the "on a stick" metaphor, it follows that someone screwed up the metaphor and it stuck. This whole argument is a great metaphor for management, by the way. Screwing up concepts and treating employees like children or mules. Either way, anyone who uses either one is a moron.

      Wow, really? I was going to respond to your first egregious abuse of this metaphor, but you went on and posted this? You must be rather young. (Note the use in the second paragraph of, emphasis mine, "Some claim [...]". Also, look at the illustration.)

      --
      I feel fantastic, and I'm still alive.
    75. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      If 20 lines of codes is your boundary of complexity, then programming is not for you. Breaking code into screen sized 'called once' sections adds unnecessary complexity, especially if you validate your inputs(as all good programmers should).
      Some things are just inheritently complex and the most efficient implementation might be rather abstract and not obvious at first. If you can't understand it at a first pass, the problem isn't necessarily the code.

      I call BS. A larger number of simpler routines does not equate to greater complexity. It's called "separation of concerns," and it is a fundamental principle of good engineering. If you did it right, input validation should be no more complex than if you do everything within a single routine. If you use a design methodology like design-by-contract, the responsibility for input validation should be clearly delegated, so you do need to duplicate it at each level.

      Most of the time, you probably do not need the "most efficient implementation." Clarity, and not efficiency, should be your primary concern until there is a proven conflict between the two. Much of the time, thanks to modern optimizing compilers, there is no significant difference in performance between your nasty "rat's nest" of a routine and one composed from simpler subroutines with equivalent functionality. I have personally replaced hundreds of lines of handwritten assembly with equivalent C code that was much easier to understand and actually performed better than the original.

      I've done it both ways, and guess which one I prefer. I work with people who have the same mindset as you, and I'd be willing to bet that there are subtle errors lurking in your 400-line masterpiece that wouldn't exist if you had spent some time figuring out how you could decompose the problem into simpler pieces.

      If you can't understand how to decompose a problem, then perhaps programming is not for you.

    76. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      Treat documentation as as valuable as code, and it will get done.

      Who is it valuable to? When is is valuable to them?

      It is likely valuable to you, right now. Being forced to explain your design in writing often uncovers design flaws that would later show up as bugs at a point in the project where they are much more costly to correct.

    77. Re:How to poke a dead body by psmears · · Score: 1

      Some guy on the usenet agreeing with you is not evidence.

      No, you're quite right. Unless that guy happens to go through in detail all the available evidence from the Oxford English dictionary.

      Maybe the evidence is not conclusive, but it is strongly suggestive—do you have any evidence for your point of view? Can you point to any uses of "carrot on a stick" in the way you describe that predate the "carrot and stick" uses from the OED? That's what it would take to demonstrate that that was the original phrase.

      And as for your assertion that the metaphor is stupid—well, that's a matter of opinion, of course, but language is a funny thing and many metaphors are indeed daft. But as for saying that "carrot" is only a reward for mules and rabbits—the point of a metaphor is that it draws a parallel between one situation and another (carrot=desirable reward, donkey=potential recipient of reward). The point is that the carrot is desirable to the donkey. Just because you wouldn't like a carrot doesn't invalidate the metaphor, any more than pointing out that the good aspect of a bad situation isn't actually made of silver would invalidate "every cloud has a silver lining" (nor indeed would pointing out the fact that clouds do not, as a rule, have linings made of precious metals).

    78. Re:How to poke a dead body by obarel · · Score: 1

      Well, I've also seen comments like this:

      /* Increase byte count by 17 */
      byteCount -= 17;

      But the comment can become useful if you only change it slightly:

      /* Skip the objectInfo structure */
      offset += 17;

      Then you don't have to search in the code where objectInfo is stored - it's clear that it isn't.

      Sometimes I find myself reading the code, explaining it to someone, and then I say "actually, that's exactly what the comment is saying..."

    79. Re:How to poke a dead body by Anonymous Coward · · Score: 0

      I worked in a similar model and templates and macros are best techniques to get started with creating software API
      documentation.

      I'd go a step forward and doxygenate it.

      Inline comments for innovative or creative code blocks are certainly good practice., as is somewhat frugal attempts
      to have enough comments to parse these into a flowchart describing the code to be written.

      In general the "form good habits" doctrine applies to commenting and maintaining code and APIs.

    80. Re:How to poke a dead body by aardvarkjoe · · Score: 1

      But the comment can become useful if you only change it slightly:

      /* Skip the objectInfo structure */
      offset += 17;
       

      Then you don't have to search in the code where objectInfo is stored - it's clear that it isn't.

      Sometimes I find myself reading the code, explaining it to someone, and then I say "actually, that's exactly what the comment is saying..."

      In that case, your comment is explaining why you're skipping 17 bytes -- something not contained within the code you just wrote -- so I don't have any objection to it. Of course, if it had been written:

      offset += sizeof(struct objectInfo);

      Then that line wouldn't have necessarily needed a comment at all, since anyone reading it would know what just happened.

      --

      How can we continue to believe in a just universe and freedom to eat crackers if we have no ale?
    81. Re:How to poke a dead body by obarel · · Score: 1

      Yes, I completely agree, of course. Having "17" in the code requires some explanation.
      In this case, I'd probably have something like:

      enum { OBJECT_INFO_SIZE = 17 };

      (my assumption here is that I need to skip a certain size in bytes in some byte stream that needs to be parsed - of course if sizeof(struct objectInfo) works then that's even better).

      But even so, someone might say "I understand that you are skipping objectInfo, but *why*?" where a comment could really help:
      /* Skipping the objectInfo strucutre, as it is optional [section 4.2.2] */
      offset += OBJECT_INFO_SIZE;

    82. Re:How to poke a dead body by Asic+Eng · · Score: 1

      You're basically saying that the creative people should be given as much free rein as they like

      Nonsense, I was saying nothing even remotely related to that. Nor was I arguing arguing anywhere that documentation wasn't important. I was however arguing that badgering won't get you there - which matches my experience and apparently yours, too. Anyway TFA makes some suggestions how to get there - it's not a particularly great article, but it's worth a look.

  2. What?! Give them more money? by L4t3r4lu5 · · Score: 2, Funny

    But money costs money!

    --
    Finally had enough. Come see us over at https://soylentnews.org/
    1. Re:What?! Give them more money? by tbannist · · Score: 1

      According to the book "Drive", it's not really a good idea to pay extra to document the code. The reward will get a temporary bump in documentation but afterward the reward period ends, the documentation will be worse than before the reward was offered. That's because the reward will erode the intrinsic motivation to do a good job, and the monetary reward will solidify the notion that documentation is a noxious chore that they should be paid extra to do (alternatively, they may get the idea that if they don't document the code they can earn bonuses later for doing something they would normally get paid extra to do).

      The best way to get better documentation is to treat your programmers like they are humans, pay them an adequate base salary and explain that supplying adequate documentation is part of their job, and that they can't do the job well if they're not providing the required documentation. Of course, this may require the manager to actually implement some processes like code reviews to provide timely feedback and reminders that documentation is needed. You might even have to, horror of horrors, refuse to accept new code that isn't adequately documented. If the programmers like their jobs, they'll be willing to make the effort to do it well.

      --
      Fanatically anti-fanatical
    2. Re:What?! Give them more money? by Moryath · · Score: 4, Insightful

      Your entire premise rests on a few bad assumptions, however:

      #1 - that the PHB will know what the fuck he is doing and adequately schedule enough time to document the code.
      #2 - that the marketing fucktards will know what the fuck THEY are doing and not overpromise or promise delivery schedules so tight that the PHB has time to allocate to documentation in the first place.
      #3 - that the company bosses are not "doing more with less" and overworking their employees to start with, relying on a down economy to fuck the working class by making everyone too scared to quit (for fear of not finding another job and being unable to support their families or being tied down by the risk of losing medical coverage) do 3-4 persons' jobs.

      Now let me tell you how the "real world", the world created by the Retardicans for the last 15 years works:
      - Employees ARE, as a general rule, overworked. The upper class HAVE, as a general rule, been playing the "do more with less" card so often that employees are doing the work that 5 years ago was done by 3 people.
      - Employees ARE, as a general rule, fucked by the system. Need to find another job? Better hope it covers healthcare. The upper class don't have to give a crap about health care, the poor will never get out of people poor because if they ever did medical bills will put them right back, and the middle class lives in daily fear of losing health care coverage and being put into the poorhouse by medical bills - for themselves, spouses, parents, kids, anyone in the family.
      - Managers are fucking assholes whose job it is not to work with the employees, not to ensure that enough time is allocated for things that need doing, but to be slave drivers. We just had a slashdot article covering the latest problem of people feeling too scared to take vacation because of how managers behave about it.

      What we need are far stronger worker protections. The Retardicans have been screaming about "obamacare obamacare obamacare" like it's some kind of bogeyman, but actually, single-payer and guaranteed healthcare coverage are GREAT for the working class, because it's removing the iron ball of "healthcare tied to your asshole fucking boss" from their legs and will let more people actually look for better jobs, or even start their own businesses without the fear of one accident or one unexpected illness ruining their entire lives.

    3. Re:What?! Give them more money? by Anonymous Coward · · Score: 0

      Yeah, and crappily documented code costs time everytime you need to fix something, and time is money. If your manager doesn't completely suck, he realizes that.

      Unfortunately, it's hard to make an objective case for how much badly commented code costs, thus proving that the monetary incentives are a net benefit; so even if your manager gets it, how the hell will he explain it to his boss with the "coding is easy, I saw on TV you can learn it in a year" mentality?

      And as sibling comment by tbannist suggests, a temporary financial incentive will not build the "culture of documentation" a company wants. A permanent financial incentive may work (won't create a culture, but will get you documented code), but without a way to prove on an ongoing basis that it _is_ saving the company money, it'll eventually get cut, and you'll be back to square one.

    4. Re:What?! Give them more money? by L4t3r4lu5 · · Score: 1

      [B]ut actually, single-payer and guaranteed healthcare coverage are GREAT for the working class...

      Kind of shot yourself in the foot there, chum. What the fuck does your boss, his boss, and the CxO care what's good for the working class? Yes, it's the modern equivalent of indentured servitude, but nobody can help those who won't help themselves. "Horse to water..." and all that. It's nobody's fault except the working class (of which I am a member) that these things are allowed to continue. Wholesale refusal to accept lowest-bid working conditions is probably not the only way, but it's a damn good start. Selling your soul for a nickel because the next guy wanted a dime just continues the trend to drive down the working wage, and the CxO laughs all the way to the bank with his 3rd Audi of the year and his salary-pension.

      It's a race to the bottom, and we're picking up speed at a ferocious rate.

      --
      Finally had enough. Come see us over at https://soylentnews.org/
    5. Re:What?! Give them more money? by JoeMerchant · · Score: 1

      Now, tell us how you really feel.

      If you want worker protections, the first place you can start is by attaining a position of self employment. I've never had the discipline to save enough money to make that possible for me and my family, but if I had lived on 1/2 of my income instead of 9/10 for the last 20 years, I could "be my own boss" right now, with enough savings to get through the lean times and pick and choose my employers and make my own protections in the terms of employment.

      Living on 1/2 my income for 20 years woudn't have been much fun, and working for "the man" isn't much fun, either. Pick your poision - or just be born to a top 1% rich family, that solves all problems.

    6. Re:What?! Give them more money? by Moryath · · Score: 2

      If you want worker protections, the first place you can start is by attaining a position of self employment.

      You try getting a "position of self employment" with a congenital condition.

      Want to take out a small business loan? Whoops - your "condition" carries a slightly higher risk, even if well managed, that you'll be incapacitated by it. So the bankers won't clear you for a loan.

      Want to try to buy health insurance for yourself or any employees? Fat fucking chance. No insurance will take you, "preexisting condition."

      Have a kid who's been born with something? Forget it, no coverage for them. Worse yet as happened to a buddy of mine who had gone the self-employed route - his kid has leukemia. Prognosis: 10 years max. 7 year old kid. Oh, to make matters worse, the health insurance company dropped his business, which leaves him, his wife, their kid, AND his 5 employees with no health insurance. To get it back, he'd have had to sign a "waiver" leaving his kid off of having insurance forevermore.

      Retardicans at work.

      but if I had lived on 1/2 of my income instead of 9/10 for the last 20 years

      You're assuming you HAD income that entire time. In the Retardican economy, chances are you've been laid off three times in the past 15 years through buyouts/acquisitions/mergers when some bigger company decided they wanted your current workplace's patents. You went through your savings each time, and maybe a little more, surviving till you were able to find another job. That's how the Retardican economic system works, unless you were born up at the top.

    7. Re:What?! Give them more money? by swalve · · Score: 1

      The key is also in insisting on good performance on day one, and then being consistent. Being a good manager is hard, because it requires them to constantly "babysit" their subordinates. Managers who do not accept this will not be successful.

    8. Re:What?! Give them more money? by Anonymous Coward · · Score: 0

      You're assuming you HAD income that entire time.

      I think the guy knows whether he had income or not, and whether or not he's been laid off, regardless of what the "chances are".

    9. Re:What?! Give them more money? by Anonymous Coward · · Score: 0

      That is MBA textbook material, MBAs are the sort of people reviled here on slashdot. Just sayin'.

    10. Re:What?! Give them more money? by Moryath · · Score: 1

      And I'm pointing out that his experience is atypical.

    11. Re:What?! Give them more money? by m.ducharme · · Score: 1

      Workers in countries with universal health care take less sick days and cost their employers less when they do get sick. That's why the bosses should want a universal health care plan (not just guaranteed, universal). Also, healthcare costs less overall, which is a net benefit for everyone. Despite what people think, there are benefits that accrue to the upper class when the middle and lower classes are kept healthy and happy.

      --
      Rule of Slashdot #0: You and people like you are not representative of the larger population. - A.C.
    12. Re:What?! Give them more money? by m.ducharme · · Score: 1

      Correction: Workers in countries with universal healthcare take less sick days or show up to work sick less often and for shorter amounts of time (and are therefore more productive)....etc.

      --
      Rule of Slashdot #0: You and people like you are not representative of the larger population. - A.C.
    13. Re:What?! Give them more money? by Kvasio · · Score: 1

      Give them less money (if they don't do docs)

  3. I like to use a big stick by M4n · · Score: 2

    Nothing else seems to work...

    --
    In space no-one can hear your vuvuzela.
    1. Re:I like to use a big stick by Anonymous Coward · · Score: 0

      I like to use a big stick

      As an incentive?
      Filthy bastard!

    2. Re:I like to use a big stick by robthebloke · · Score: 2

      Just move the offending developer to another poorly documented part of the codebase. Repeat that a few times, and they soon learn why code comments are a good idea....

    3. Re:I like to use a big stick by M4n · · Score: 2

      They seem to like it

      --
      In space no-one can hear your vuvuzela.
    4. Re:I like to use a big stick by Hognoxious · · Score: 2

      You're an Apple shop, right?

      --
      Confucius say, "Find worm in apple - bad. Find half a worm - worse."
    5. Re:I like to use a big stick by spooky_d · · Score: 3, Insightful

      Or they will show you why code comments are a bad idea.

      Code comments are usually unmaintainable artifacts; misleading at best.

      The best kind of documentation is architectural description of the solution. Everything else is just rubbish. I want to see code comments WHEN they are needed - and the fewer the better. If you write your code in such a manner that it needs documentation, then you might have done a bad job ad writing code.

      Example of moments when you NEED to document code: module boundaries, interfaces and implementation hints for when the code needs extension. But by no means should one document EVERY call; but the most important ones. Code samples would help.

      Just some programmer's opinion

  4. Mandate works best by Nickodeimus · · Score: 2, Insightful

    In this case, mandate works best because this is something that the developer SHOULD be doing anyways. Not documenting your code is inexcusable.

    1. Re:Mandate works best by netwarerip · · Score: 2

      But in a small to midsized shop, undocumented code is akin to job security (in developer's minds at least).
      If I had a nickel for every time I heard "Oh, be careful with what you say to (insert developer's name here), he is the only one that knows how the Widget process works." When I ask where the documentation is on it I get a blank stare, or worse, I get "Well, we asked him to do that but he says he's too busy."
      Ok, maybe that's more of a sign of lazy, ball-less management, but it still sucks.

    2. Re:Mandate works best by Anonymous Coward · · Score: 0, Flamebait

      Mandate? You mean threaten them with a homosexual encounter if they don't comment their code?

    3. Re:Mandate works best by Anonymous Coward · · Score: 5, Funny

      /**
      * For the brave souls who get this far: You are the chosen ones,
      * the valiant knights of programming who toil away, without rest,
      * fixing our most awful code. To you, true saviors, kings of men,
      * I say this: never gonna give you up, never gonna let you down,
      * never gonna run around and desert you. Never gonna make you cry,
      * never gonna say goodbye. Never gonna tell a lie and hurt you.
      */

      //When I wrote this, only God and I understood what I was doing
      //Now, God only knows

      // I dedicate all this code, all my work, to my wife, Darlene, who will
      // have to support me and our three children and the dog once it gets
      // released into the public.

      // somedev1 - 6/7/02 Adding temporary tracking of Login screen
      // somedev2 - 5/22/07 Temporary my ass

      R.I.P - best question ever.

    4. Re:Mandate works best by Anonymous Coward · · Score: 0

      My code is self documenting.

    5. Re:Mandate works best by Anonymous Coward · · Score: 5, Insightful

      Maybe it's a sign that the developer really is busy. Most places I've worked it's the developers who ask for additional project time to document code and aren't granted it because it's seen as a non profit generating part of the project (why have coders writing documentation for a finished project when they could be building the new project). It's shooting yourself in the foot for the future if you ever need to change anything in the code, but again, if that time is billable then efficiency savings from proper documentation are a very hard sell.

    6. Re:Mandate works best by LordLucless · · Score: 3, Informative

      No, it's perfectly excusable.

      Not giving your developers time to write documentation, by piling on another deadline as soon as the last bolus of code has been shoved out into production, yet still demanding that documentation somehow appear - that's inexcusable.

      --
      Just because you're paranoid doesn't mean there isn't an invisible demon about to eat your face
  5. code documents itself by lynnae · · Score: 3, Insightful

    I prefer the theory that well developed code is it's own documentation. (believe this comes from reading a lot from Uncle Bob)

    Crud loads of javadoc/msdn like documents aren't as effective as readable code and a few real world examples.

    1. Re:code documents itself by Anonymous Coward · · Score: 1

      Your code should read easily. Developers making code complicated because they think it's smart just makes me cringe. But I disagree that comments are unneccesary. Comments should be there to explain the thinking of why something was done that way. Personally, I comment my code to remind myself when I have to come back to it. The fact it also makes the code easily maintainable is a bonus.

    2. Re:code documents itself by quintus_horatius · · Score: 5, Insightful

      In my experience, self-documenting code generally isn't.

      Proper documentation never explains what you're doing - that's what the code is for. Documentation explains why you did the things you did, which is difficult to express in self-documenting code.

    3. Re:code documents itself by ifrag · · Score: 1

      I think the main problem is that some developers do not seem to realize WHEN the code can stand on its own, and WHEN having a bit of explanation is important. So the knee jerk reaction to this is just "we need more comments / documentation".

      A lot of useless comments in completely obvious code adds absolutely nothing to the program, and in fact probably just makes it more difficult to read. A lack of comments in an extremely complicated algorithm or non-typical solution will probably result in someone breaking it later because they either think it is doing something else, or just don't get it.

      Also, in terms of where it is located, I think developers are at least more likely to keep some description or outline in the code comments up to date, compared to say a separate document. So unless it is being sucked in from some automated tool like doxygen, I'd consider offline documents secondary to whatever is right in front of you.

      --
      Fear is the mind killer.
    4. Re:code documents itself by sgtwilko · · Score: 3, Insightful

      I prefer the theory that well developed code is it's own documentation.

      I'm a Very strong believer in self documenting code, I simply don't allow my team to create objects, variables, functions, etc that don't tell you what they do.

      I'm also a strong believer in adding comments to code. Good, self documenting, code should tell you what it is doing without comments, but often the reason Why it needs to do things are is lost or cannot be conveyed in the code.

      tl;dr:
      Well written code tells you what it does.
      Well documented code tells you why it does what it does.

    5. Re:code documents itself by AmiMoJo · · Score: 1

      It amazes me how many programmers fail at the simplest of things, like putting units in variable names (engine_temp_c or battery_level_mv). If you can't write code that is readable and makes sense to others then you can't write code.

      --
      const int one = 65536; (Silvermoon, Texture.cs)
      SJW, n: "Someone I don't like, and by the way I'm a fuckwit" - AC
    6. Re:code documents itself by delinear · · Score: 1

      Indeed, there might be several different ways to achieve the same outcome with non-obvious advantages/disadvantages. No matter how elegant the code is, it tells you nothing about the reason for that particular implementation (say you're relying on a third party web service that's flaky or slow unless you format the request in a certain way).

    7. Re:code documents itself by slim · · Score: 1

      I think the way Uncle Bob puts it is that including a comment is an admission that you're unable to write code that's as expressive as you'd like.

      *But* there's nothing wrong with making that admission. The flow is:


      while(code can be made more readable within practical constraints) {
            make code more readable
      }
      if(code is readable enough to not require comments) {
            great!
      } else {
            write a comment
      }

    8. Re:code documents itself by apcullen · · Score: 4, Interesting

      If by "self-documenting code" you mean code with milti-paragraph long comments in it explaining in detail what each section does and how it's intended to work, with a detailed change log at the top of each section of the code, then I agree with you.
      However IME to most developers "self-documenting code" means something more like "you should be smart enough to know how this works from reading my semi-descriptive variable names". I've seen comments like "Here's the main routine. This is fun" in some code that I've picked up and had to maintain. Made me shake my head at the time.
      When I first started my career, I met a developer who put a comment on almost every line of his code. When I asked him why, he said, "because I try to code like the next person who's going to look at what I did is an idiot. And it usually is. It's usually me". I laughed at the time, but as I've grown older I've come to realize how true it is.

    9. Re:code documents itself by Pokermike · · Score: 2

      Yes and no. Well written code tells fellow developers on the project how something works and shouldn't require a lot (if any documentation). However, if I'm using someone else's code I don't always want to have to read through it to figure out what it does. Documentation (like Javadoc) should be used to explain what the code does (without getting into the details of how). In some cases, a few real world examples may be enough.

      <rant>
      This is my problem with many open source projects. Usually the only way to use it in your own project is to open up their source code and start reading through it. And if there is any documentation, it's frequently woefully lacking and/or out of date. And tweaking their sample code doing "trial and error development" sucks.
      </rant>

    10. Re:code documents itself by LordLucless · · Score: 1

      In my experience, the thing that self-documenting code documents best is that the person who wrote it was an arrogant dick who thought he was above everyone else.

      Sometimes, you need to take a non-obvious approach. In those cases, you should document why you took that appraoch, so that some well-meaning developer doesn't come by in a couple of years time, and refactor crucial logic out. Sometimes, you're implementing a complex algorithm that's not immediately apparent by looking at the string of mathematical operations it consists of. A simple comment with a link to a page describing the algorithm, and suddenly everyone knows what it's supposed to do.

      "My code's self documenting" is just code for "I think I'm too good to deign explaining myself to lesser mortals - my time is too valuable. They can spend their time trying to understand my code instead".

      --
      Just because you're paranoid doesn't mean there isn't an invisible demon about to eat your face
    11. Re:code documents itself by Kagetsuki · · Score: 1

      There's a document in the Linux kernel source that outlines coding style, and exactly this is mentioned in detail and very clearly outlined. Taking the time to name things properly and to USE white space and line breaks in a way that makes things clear makes most comments irrelivant. Really unless you're doing some strange/complicated/magic operations you shouldn't need any comments other than general function/class descriptions.

    12. Re:code documents itself by LoztInSpace · · Score: 1

      Exactly.
      And this is why you should not, as a general case really try to document intent in code other than in reference to requirements. The requirements, specifications, release notes and high-level architecture design documents are there to describe the nature and features of the product. The code is how it gets you there and how it works should be self documenting.
      The "should this value be 20 or 21", "should it ask a or b", "does it report x or y" kind of things are not to be found in code but in product documents.
      That way they behaviour and features are testable, publishable, sellable, supportable. Not every interested party can read code. Furthermore, in mature organisations the code is often a small part of a large operational process.

    13. Re:code documents itself by Anonymous Coward · · Score: 0

      Self-documenting code doesn't tell you *why* you are doing something which is often the most important thing when coming back to maintain some code.

    14. Re:code documents itself by Anonymous Coward · · Score: 0

      Well, the code could be completely clear and self-explanatory, but if it doesn't actually do what the programmer intended it to do, it's absolutely worthless. And, that's really what documentation should be doing - explaining why, not what. Any reasonably competent programmer can figure out what code by any other reasonably competent programmer DOES, but not WHY it's that way, or what its' SUPPOSED to do.

    15. Re:code documents itself by archen · · Score: 1

      The problem is that this expects the person who reads the code to inherently understand your mentality and logic. There are batches of code which look screwy, but eventually you can "figure out" what the person was thinking in what they were trying to do. But often this isn't the case. If solutions were as easy as describing them, then anyone could program. I don't believe in obsessively commenting every line, but having a simple commented explanation of what something is supposed to do can make it vastly easier to see why or why not their solution is right or wrong.

    16. Re:code documents itself by Anonymous Coward · · Score: 0

      I agree with your point that real documentation is something that can't be handled by coding clean but one of my favorite quotes from Code Complete makes a wonderful point...

      "Construction's product, the source code, is often the only accurate description of the software In many projects, the only documentation available to programmers is the code itself. Requirements specifications and design documents can go out of date, but the source code is always up to date. Consequently, it's imperative that the source code be of the highest possible quality. Consistent application of techniques for source-code improvement makes the difference between a Rube Goldberg contraption and a detailed, correct, and therefore informative program. Such techniques are most effectively applied during construction." - Code Complete

    17. Re:code documents itself by dkf · · Score: 1

      I prefer the theory that well developed code is it's own documentation. (believe this comes from reading a lot from Uncle Bob)

      For learning about what the code does? Sure. For learning why? No. That's when you need comments and external documentation. (With code, all other questions tend to be subservient to those two: what is happening and why.)

      The best comment I ever saw in code though was simply a reference to an academic paper that described the algorithm used in depth, including all the magic numbers and bits that made you thing "WTF?!". Documentation doesn't usually need to be long, but it does need to be informative.

      Crud loads of javadoc/msdn like documents aren't as effective as readable code and a few real world examples.

      Neither is a substitute for the other, and good API documentation will include some stripped-down examples. (Not all API docs are good.) Bear in mind that a full real world example is usually bloated up with stuff to deal with other necessary things; great if you're solving that real world problem, but crap for understanding an API's use.

      And of course, not everything you need to document is an API. It can be necessary to add docs to the trickier parts of the implementation too.

      --
      "Little does he know, but there is no 'I' in 'Idiot'!"
    18. Re:code documents itself by JoeMerchant · · Score: 1

      I prefer the theory that well developed code is it's own documentation.

      Yes, it is. IME, most people who claim their code is well developed enough that it needs no documentation, are wrong.

    19. Re:code documents itself by SecurityGuy · · Score: 1

      I think this is true, and the worse offenders are those who think code can document itself. In all but simple cases, it can't. My pet example is that code can at best document what it does, not what it's supposed to do. If I write comments to indicate what a function/section of code/etc is supposed to do, you can check it later to see if it really does. I had a nightmarish problem with OpenBSD locking up on me that proved impossible to debug because I was following a twisty little maze of functions, none of which actually said what they were supposed to do.

    20. Re:code documents itself by Zerth · · Score: 3, Insightful

      Indeed, even if your code is complete clear on what it is doing, you should at least put in a comment on *why* it is doing what it is doing.

      Obviously, I used algorithm A, but why did I pick it over algorithm B. Is it because B isn't faster in this particular case or because A is less memory intensive, etc.

    21. Re:code documents itself by Anonymous Coward · · Score: 0

      I prefer the theory that well developed code is it's own documentation. (believe this comes from reading a lot from Uncle Bob)

      Crud loads of javadoc/msdn like documents aren't as effective as readable code and a few real world examples.

      Couldn't agree more. Every developer should read "Clean Code." By far the most influential book I've read as a developer.

    22. Re:code documents itself by avandesande · · Score: 1

      It really depends on what you are doing- if you are working on a regular pattern and doing basic database IO, then I think code can be self documenting. If you are doing complex algorithms or transformations comments can be very helpful.

      --
      love is just extroverted narcissism
    23. Re:code documents itself by neiko · · Score: 1

      I wholeheartedly agree. There's nothing worse than coming across documentation that was clearly cut-n-pasted from another function but never revised to reflect the actual function someone is documenting, or comments that are so old and out-of-date that no one remembers if they are relevant/true anymore. Writing documentation for new code is easy, it's the upkeep by other developers that completely renders it useless. Documenting a public interface so that Doxygen can generate some good output is worth-while, or a complex mathematical expression that has a lot of constants in it, but that's where I stop.

    24. Re:code documents itself by MobyDisk · · Score: 3, Informative

      If by "self-documenting code" you mean code with milti-paragraph long comments

      That is not what the term "self-documenting code" means. It actually means the opposite of that. The term refers to code with no comments, where the variable names, function names, etc. are so well-named that comments are less necessary. For example:


      float CalcPatients()
      { // Calculate an estimate of the number of patients based on
      // the number of beds per room,
      // the number of rooms, and the average occupancy rate. Since
      // this uses an average
      // occupancy rate, it is just a guess rather than an actual number.
      // So you might get fractional patients.

            return bpr * r * o;
      }

      float EstimateNumberOfPatients()
      {
            int beds = bedsPerRoom * rooms;
            int patients = beds * occupancyRate;
            return patients;
      }

      The latter is the self-documenting version.

    25. Re:code documents itself by quintus_horatius · · Score: 1

      However IME to most developers "self-documenting code" means something more like "you should be smart enough to know how this works from reading my semi-descriptive variable names".

      If it was hard to write, it should be hard to read.

    26. Re:code documents itself by lehphyro · · Score: 1

      In self-documenting code you generally only need to explain why you did something some way if you do something unusual, a large part of the code is/should be very straightforwad.

    27. Re:code documents itself by RobertLTux · · Score: 1

      good comments can answer the "WHAT WAS HE SMOKING??!!@!" type questions and warn you that this hazmat grade ugly section of code is required to make sure that a CANT HAPPEN case in the code actually CAN NOT HAPPEN.

      please note if you do code while "chemically enhanced" please don't literally say so in your comments.

      --
      Any person using FTFY or editing my postings agrees to a US$50.00 charge
    28. Re:code documents itself by Anonymous Coward · · Score: 0

      libjpeg was like this when I used it. Each API had about a screen full of /* */ comments above it. I'm not even sure if there if the APIs are documented in the accompanying text files. The README probably describes the directory structure. The library is very useable, and is used in thousands of other software packages.

      Good developers write this kind of documentation all the time.

      The problem is that management wants a Word document separate from the code before the code is even finished. The developers know that nobody will read it. They know that by the time it's done while concurrently adding features, it will be obsolete. Because the documentation is separate from the code, it has less chance of being useful.

      Some managers seem to evnsion this mythical sort of documentation that would allow non-technical people to understand the code and use it. If such a documentation format existed, we would be coding in that format, not C, Perl, Java, etc.

      A more reasonable yet still misguided belief on the part of management is that there is documentation that will allow other engineers to understand the code. There is but only up to a point. Past that point, the code is the documentation. They should look to the most commonly used OSS as their guide.

    29. Re:code documents itself by nschubach · · Score: 1

      /* We should be making code more readable so we don't need comments unless code is already readable. */
      while(code can be made more readable within practical constraints) { /* make code more readable */
              make code more readable
      }
      if(code is readable enough to not require comments) { /* do it! */
              great!
      } else { /* write a comment */
              write a comment
      }

      --
      Every time I start to have faith in humanity, I ruin it by driving to work between 7 and 8 am.
    30. Re:code documents itself by nschubach · · Score: 1

      So if a program you wrote needs to be changed to Fahrenheit or Kelvin someone has to change all your variable names or create additional variables that are populated with the converted values?

      Seems like a bad practice.

      --
      Every time I start to have faith in humanity, I ruin it by driving to work between 7 and 8 am.
    31. Re:code documents itself by englishknnigits · · Score: 1

      Generally agree. However, there are a few exceptions. It should be mandatory in "published", rarely changing interfaces so people don't have to look at the implementation behind the interface. Documentation is nice for utility classes that get used all the time and across projects (like some fancy list). Documentation is also good for code that is dense and difficult to understand by its very nature (large equations are a good example). Generally, code should be made less dense and difficult to understand instead of documenting it but that cannot always be avoided.

    32. Re:code documents itself by radtea · · Score: 2

      I prefer the theory that well developed code is it's own documentation.

      I prefer the theory that developers who prefer the theory that well developed code is its own documentation are lazy and/or incompetent, so I don't hire them.

      --
      Blasphemy is a human right. Blasphemophobia kills.
    33. Re:code documents itself by radtea · · Score: 2

      The latter is the self-documenting version.

      The number of patients per what? Floor? Hospital? Wing?

      Neither version is well-documented, although the latter is better. All it needs is one line at the top saying, "Patients per based on average room occupancy rate" or something like that.

      One of the things that good comments do is provide context, and people who claim code is "self documenting" are generally junior developers who have never experienced how ad hoc code reuse and requirements drift can silently violate contextual assumptions in a way that introduces subtle bugs that aren't found until they bite you. Putting the context in the docs makes it easier to repurpose code properly and safely.

      --
      Blasphemy is a human right. Blasphemophobia kills.
    34. Re:code documents itself by shutdown+-p+now · · Score: 1

      Well written code tells you what it does.
      Well documented code tells you why it does what it does.

      This. Print it, frame it, and hang it on the wall in every developer's office.

    35. Re:code documents itself by PickyH3D · · Score: 1

      The entire problem with that theory is that the code only makes sense when you are making the same assumptions. If I go into a blob of code assuming something different from my coworker, then we will expect the code to do two different things.

      For me to figure out their assumptions, without comments, then I will have to read far more than many the lead function that could have been documented to explain its constraints.

      This includes, but is not limited to:

      1. Can I pass in null? (And how many layers do you have to dive in to find out the real answer?)
      2. What are the actual range of values?
      3. Does the method return null? Under what circumstances?
      4. What will cause an exception under reasonable conditions (and, in the case of Java, particularly RuntimeExceptions)?

      In practice, I have found that code that is undocumented is rarely reusable by someone other than the original developer. The act of documenting your own code usually brings out design flaws, and hopefully leads to simplified code because you do not want to document too much. I also find that most people holding similar beliefs ignore unit testing as well, or they write only the simplest boilerplate tests that really do not test much at all.

      I can also say that I will never intentionally hire someone that holds the belief that well developed code is its own documentation. Well developed code lends itself to documentation, both through easier documentation and requiring less of it, but that is all. It's stupid to require other developers--or even yourself further down the road--to have to jump through hoops to figure out if a NullPointerException is in their future.

    36. Re:code documents itself by Anonymous Coward · · Score: 1

      They don't do the same things, or the first one is documented wrong.

      Assuming the first one is correct, then this shows why documentation is important. The error in the second could easily be missed if there was no comment.

    37. Re:code documents itself by thermal_7 · · Score: 1

      Shit yes. This is especially important when not so obvious bugs force a change in the code. If the why isn't explained through comments, other developers are likely to change it back to the simple solution with the bug.

    38. Re:code documents itself by Anonymous Coward · · Score: 0

      Disagree. The code drift makes the comment useless most of the time. The violation occurs and the context doesn't get updated, but the code did.

      he could have improved his patients variable to answer your question or changed the function name or both.

      the code can lie (the names) too, but it is *more* likely to be closer to reality than the comments. Lots of developer's don't event read the comments.

    39. Re:code documents itself by Thing+1 · · Score: 1

      people who claim code is "self documenting" are generally junior developers

      Exactly; the complexity of the solution is dependent on the complexity of the problem. Providing a simpler solution than the problem space, generally results in a solution that has edge cases which fail. We prefer not to fail.

      --
      I feel fantastic, and I'm still alive.
    40. Re:code documents itself by AmiMoJo · · Score: 1

      If you need to convert to different units you are going to have to change much more than just the variable names. In fact you might only change the display and keep the internal working in the original units since the code works and can be kept in sync with further updates. In that case adding the units to any variables is a really, really good idea if you don't want to get mixed up.

      In the case of a full conversion then search/replace or code refactoring is easy enough.

      --
      const int one = 65536; (Silvermoon, Texture.cs)
      SJW, n: "Someone I don't like, and by the way I'm a fuckwit" - AC
    41. Re:code documents itself by Anonymous Coward · · Score: 0

      Just curious - why is that a float? Do you have half a patient lying around in a bed somewhere?

    42. Re:code documents itself by Anonymous Coward · · Score: 0

      Assuming the first one is correct

      The first one might tell you that you have 3/5ths of a person, you fucking racist.

    43. Re:code documents itself by Anonymous Coward · · Score: 0

      Why are we debating documenting code? We are documenting documention problems.
      There are people who believe in self-documenting code, and there are people who can remember how their APL programs worked ten years later.
      I'm not either. I'm just mortal.
      I don't think this issue is solvable. My guess is that it's just too much fun to create puzzles, and watch other people try to solve them, in code.

      I hope that if nothing else, this gave ya a smile.
        -- dave small

    44. Re:code documents itself by DutchUncle · · Score: 1

      Code can be self-documenting. Comments are for explaining why you did the things you did (that is, not for explaining that "a++;" means "increment a") and for explaining something clever or sneaky (if I manage to optimize a paragraph down to a line, I'll write a paragraph of comments explaining how).

      Using meaningful names is IMO the single most important thing for clarity. Some people seem to like Humpty Dumpty's approach of using words to mean whatever they want and paying them extra on the weekend; then they cant remember what's going on when they themselves look at the code six months later.

    45. Re:code documents itself by slim · · Score: 1

      High five!

  6. Indians will appreciate your docs by muon-catalyzed · · Score: 5, Funny

    Once the boss learns about financial advantages of outsourcing.

    1. Re:Indians will appreciate your docs by Robert+Zenz · · Score: 4, Funny

      Upcoming next article: "How to get Indian companies to document the code I payed for?"

    2. Re:Indians will appreciate your docs by Inda · · Score: 1

      Complete with spelling mistake!

      That would be a Slashdot first!

      Paid.

      --
      This post contains benzene, nitrosamines, formaldehyde and hydrogen cyanide.
    3. Re:Indians will appreciate your docs by Anonymous Coward · · Score: 0

      His documentation would stink, he/she would be better off not documenting the code. There is the first smell of code documentation.

    4. Re:Indians will appreciate your docs by Anonymous Coward · · Score: 0

      I am professional code documenter, and "Payed" is my name, you insensitive clod!

    5. Re:Indians will appreciate your docs by dintech · · Score: 5, Funny

      And in our end-of-year special: "Why do my Indian offshore partners send back code that has Chinese comments in them?"

    6. Re:Indians will appreciate your docs by Robert+Zenz · · Score: 1

      +1 Funny if could!

    7. Re:Indians will appreciate your docs by Anonymous Coward · · Score: 0

      you are giving Indians ideas...

  7. Management issue by Anonymous Coward · · Score: 3, Insightful

    Management says "do X" as fast as you can. Programmer does X and report back. Documentation, like proper testing or elegant design, takes time and thus cost money. It often saves cost over the long term but if the management doesn't care why should the programmer ?

    1. Re:Management issue by Chrisq · · Score: 2

      Management says "do X" as fast as you can. Programmer does X and report back. Documentation, like proper testing or elegant design, takes time and thus cost money. It often saves cost over the long term but if the management doesn't care why should the programmer ?

      I've been there early on in my career. I had a tight deadline to produce something for the first iteration of testing. I said "its done but I need to document it. I was promptly told "we'll document it if we have any problems with it" and moved on to the next project.

    2. Re:Management issue by Anonymous Coward · · Score: 0

      Because you are a professional and you want to do a good job and be praised by your co-workers and be happy in the future when you have to maintain your own code.

      Why not to write good code: Because you suck or you are lazy. Most often the reason is because you are lazy. I know this, because I'm lazy also. But I try to improve. I started improving by not only improving my own old code, but also improving old code written by others. You know that class everyone bitches about being hard to use? Fix it. You know that class that is obvious duplicate of another class? Remove the duplicate. You know that variable which name is foo even it contains bar? Fix it. Very small changes can improve code quality a lot.

    3. Re:Management issue by olau · · Score: 1

      ... why should the programmer ?

      Because he or she's a pro?

    4. Re:Management issue by assertation · · Score: 1

      It often saves cost over the long term but if the management doesn't care why should the programmer ?

      Because the programmer may be asked to update his code. With comments it can be a ten minute job, without comments a major hassles if the programmer hasn't looked at that code in a long time.

    5. Re:Management issue by dave87656 · · Score: 1

      That is something I've experienced a lot over the years and what I've found works over time is simply reminding yourself to insert a few comments about what the code is trying to do in each section. It doesn't take long and it helps a lot later. I don't always do it but everything else takes too much time and doesn't deliver as much benefits so you wind up not doing it.

  8. Documentation good, comments bad by WillerZ · · Score: 3, Insightful

    If what you need documenting is at the level of comments within a file your problem is not that your programmers aren't writing comments it's that they are not sriting good software. If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.

    I'll make an exception for comments to explain why a given piece of code is not actually batshit insane but required to work with a third-party library you have to use.

    Producing documentation that spans classes and discusses how things are designed to work at run-time is, however, part of the job.

    --
    I guess today is a passable day to die.
    1. Re:Documentation good, comments bad by Anonymous Coward · · Score: 1

      As a scientific programmer I strongly disagree with you. Good code should of course be self explaining. But good comments are useful in describing why for example some complicated algorithms are used on some specific input data. From the code you should be able to understand how things are done. But for complicated issues you need comments on why things are done the way they are.

    2. Re:Documentation good, comments bad by mattpalmer1086 · · Score: 1

      I completely agree that code should be clearly written - but this does not obviate the need for documentation.

      Good documentation should explain the why of difficult design decisions. It should also explain the general contract the code is offering - e.g. whether nulls can be returned, or under what circumstances, what errors can be produced under what circumstances, etc. I really don't want to have to read and understand every little bit of someone else's code just to be able to use it productively.

      On the flipside, I have seen a lot of completely useless documentation which just re-iterates what is already blindingly clear from the code itself.

    3. Re:Documentation good, comments bad by Anrego · · Score: 1

      I find general comments covering chunks of code to be useful when skimming through code, but agree that a lot of comments are redundant in well written code.

      I definitely agree that higher level documentation is where it counts. I can read through a class and figure out what it does pretty quickly.. but figuring out how 100 classes interact is very time consuming. A quick little diagram can be invaluable.

    4. Re:Documentation good, comments bad by K.+S.+Kyosuke · · Score: 4, Insightful

      If what you need documenting is at the level of comments within a file your problem is not that your programmers aren't writing comments it's that they are not sriting good software. If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.

      They should be all forced to pass HtDP with all exercises done properly and I bet a lot of them would actually start writing quality code (both quality as in "less bugs" and quality as in "readable"). I love the Amazon comment where a CS PhD admits that reading the book actually taught him to write code properly.

      (I have pretty much the same experience, having been subjected years ago to a typical "learn-the-syntax-of-Pascal-and-a-dozen-sorting-algorithms"-style first year of CS at my uni. But they never got around to teaching us how make your brain come up with code like the one in those nice textbook examples in the first place, what are the recurring code patterns (*not* design patterns, mind you). They have never ever once explained how to systematically go (for any problem in general) from a problem formulated in words to a working, readable code. Much like what Dijkstra about the contemporary math education - people memorizing proofs but having no idea how to "do math" in the first place, and teachers hand-waving every objection with saying that studens must "grow some intuition", but never explaining the processes involved explicitly. I believe I eventually got to the point where I started seeing the patterns, but explicitly formulated knowledge could have shortened the process by *years*. Go read the book, do the chores, see for yourself.)

      --
      Ezekiel 23:20
    5. Re:Documentation good, comments bad by CadentOrange · · Score: 1
      He covered that in his exception. He says:

      I'll make an exception for comments to explain why a given piece of code is not actually batshit insane but required to work with a third-party library you have to use.

    6. Re:Documentation good, comments bad by djchristensen · · Score: 5, Insightful

      If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.

      This is a naive viewpoint that gets repeated over and over, most likely from people who've never actually implemented or maintained anything more complicated than "hello, world". As a developer I strive to write the simplest possible code (but no simpler!) to solve a problem, but often that code is complex enough or is based on some non-obvious assumptions (device drivers, anyone?) that I can't even remember later exactly why something was done the way it was. Sure, if you write code for relatively simple problems that don't have to interact with other complicated pieces (like the OS or any libraries), you might get away with little or no documentation within the code, but that's not the world I live in.

      I do agree with others that external documentation is just as if not more important than internal comments. And while I'm very good with internal comments, I have to sheepishly admit I pretty much suck at doing the arguably more useful external documentation. Perhaps I haven't been adequately incentivised to do that, but then in most environments I've worked in, I get poked fun at for the level of comments I put in my code, not because they are excessive or unnecessary, but because most other code has almost no comments at all, so my code tends to stick out more than it should.

    7. Re:Documentation good, comments bad by __aaltlg1547 · · Score: 2

      Wrong. Comments should describe what programs are for, what assumptions it makes about parameters, classes, data structures, etc.

      If you have to read complex program code to figure out what it does, you are in trouble.

    8. Re:Documentation good, comments bad by sourcerror · · Score: 1

      No, he didn't. GP is about "quirksmode". Parent isn't.

    9. Re:Documentation good, comments bad by fermion · · Score: 1
      I spent a fair amount of time in my younger day working on legacy code. One thing I did is ignore any comments that actually talked about how function worked. It was probably that the code had changed and the comment had not, so the comment would be useless.

      What I do look for are descriptive function names. Reading through code should be like reading an easy book. For instance, each function should do one thing. A descriptive name and clear code has always been enough for me. Coding is not like literature, there are no points for writing obsessively beautiful bullshit. I am not talking about insanely long variable names. I am talking about code that someone familiar with the art can decode in their head.

      Which of course is what this argument is about now. It takes skill to write code that can be read by a skilled code monkey. It takes skill to read such code. It is often easier to hire unskilled labor and then complain about the product rather than hiring skilled labor.

      --
      "She's a scientist and a lesbian. She's not going to let it slide." Orphan Black
    10. Re:Documentation good, comments bad by olau · · Score: 1

      I do agree with others that external documentation is just as if not more important than internal comments.

      It's interesting you say that, because, with the exception perhaps of library code with a well-defined API, it's my impression that external documentation has a tendency not to be updated and expanded, and therefore quickly lose its value, hence not being such a great idea after all.

    11. Re:Documentation good, comments bad by shutdown+-p+now · · Score: 1

      If you don't need comments, and meaningful class/function/variable names are enough to describe what the code does to sufficient detail that maintenance of said code does not involve wasting time trying to figure out what it does, it's highly likely that you're working on something like a data entry web app, or something similarly trivial.

      Now go try writing a JS JIT compiler with not a single line of comments in it.

    12. Re:Documentation good, comments bad by Anonymous Coward · · Score: 0

      Disagree about it being a view point, since I don't consider myself naive and I've done lots of different types of development from single person to large team development over the course of a couple decades and that is my view point.

      I suspect that if you could work with someone that does it well you would find you could improve your style and get the benefit.

      The assumption breaks down if you have severe limits on name lengths.

      Also "no benefit" is clearly overstating. There are always uses for good comments, but many developer's over comment and a 3rd or 4th or 85th developer that makes a change doesn't update the comment. And unless you verify the comment, then you don't know if what it says about the code is true.

      Comment "why" and "tricky bits", but if you find you write lots of comments, then your names and structure are probably less than optimal.

  9. Hire document experts by Maximum+Prophet · · Score: 4, Interesting

    I took a class at University many moons ago in software documentation. I got an 'A', and it was a valuable class in that I learned I sucked at it. (But I was better than most of the students)
    The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.

    As long as you hire great programmers you are going to get great programs. If you want great documentation, you need a great documentor.

    --
    All ideas^H^H^H^H^Hprocesses in this post are Patent Pending. (as well as the process of patenting all postings)
    1. Re:Hire document experts by lkcl · · Score: 5, Interesting

      The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.

      As long as you hire great programmers you are going to get great programs. If you want great documentation, you need a great documentor.

      it's funny you should mention this, because somewhere about 3 years ago wasn't there a slashdot article about some entrepreneur who didn't hire computer science majors (this was the U.S...) he hired english language majors and then trained them to program?

      the end-result was that he got people who produced better results because they were better able to express themselves and had already been trained to handle and comprehend more complex structures than people who thought they could program.

    2. Re:Hire document experts by Monchanger · · Score: 1

      Trained them to program? English majors? I'm having flashbacks to yesterday's CodeAcademy story.

    3. Re:Hire document experts by ciderbrew · · Score: 2

      That reminds me. Must get a gymnast for a mistress.

    4. Re:Hire document experts by Anonymous Coward · · Score: 0

      When all you need is code monkeys who do not ask questions, then perhaps that is a good choice.

    5. Re:Hire document experts by sandytaru · · Score: 1

      This this this. A technical writer who knows what they're doing will do it better, faster, cheaper, more accurately, and can be dedicated to it full time. Writing code and writing documentation for code requires two completely different mindsets, and someone who is great at one is probably not going to be that good at the other one. That isn't to say that a good writer doesn't need to know how programming works, or a good programmer doesn't need to know anything about documentation. But on large scale projects, it's just better to have someone dedicated to documenting the entire thing start to finish and let the programmers worry about making it actually work.

      --
      Occasionally living proof of the Ballmer peak.
    6. Re:Hire document experts by sandytaru · · Score: 1

      Hey now, we English major undergrands / CS master's students do exist. We're just a rare breed.

      --
      Occasionally living proof of the Ballmer peak.
    7. Re:Hire document experts by Monchanger · · Score: 1

      Heh. No offense intended there. I love the English major friends I made in college. They're some of the most awesome geeks I know, and I happened to keep in touch with more of them than the CompSci crowd to which I belonged.

      So while I'm sure they're capable, none of them cared to move into technology. That makes the intentional hiring of your rare breed an exercise in futility. An expensive one too, if you need a PhD to get the desired quality.

    8. Re:Hire document experts by Tablizer · · Score: 1

      The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.


            (2B || !2B)

    9. Re:Hire document experts by Maximum+Prophet · · Score: 1

      A history major might also be good at this, as most long term projects are studies in history. (Why the hell did we do this?)

      --
      All ideas^H^H^H^H^Hprocesses in this post are Patent Pending. (as well as the process of patenting all postings)
    10. Re:Hire document experts by Anonymous Coward · · Score: 0

      We've got that class at our college. Technical Writing. It never makes because invariably only one or two students sign up.

    11. Re:Hire document experts by phantomfive · · Score: 1

      it's funny you should mention this, because somewhere about 3 years ago wasn't there a slashdot article about some entrepreneur who didn't hire computer science majors (this was the U.S...) he hired english language majors and then trained them to program?

      Ironically, in many modern English programs, the output of their students is less readable than from programmers. A lot of modern English professors try to emulate James Joyce, whose work is admired partially because it is difficult to understand.

      --
      "First they came for the slanderers and i said nothing."
    12. Re:Hire document experts by Anonymous Coward · · Score: 0
  10. Don't Accept by Aladrin · · Score: 4, Informative

    Or simply don't accept code that isn't up to snuff. That includes documentation and testing. Peer review will help make this happen automatically. Here's how it goes:

    "I can't tell what this code is supposed to do."
    "It toggles the widget's status."
    "Is that documented somewhere?"
    "No."
    "Let's get that done."

    You don't have to have this happen too many times before you just do it to avoid that. Same as all the other good code practices.

    If you aren't doing peer review, you aren't getting the best code you could. It seems painful at first, but good developers actually like getting feedback on their code, and improving it. It isn't long before any good developer comes to desire it, instead of dread it.

    --
    "If you make people think they're thinking, they'll love you; But if you really make them think, they'll hate you." - DM
    1. Re:Don't Accept by dkleinsc · · Score: 4, Insightful

      You also need a culture that encourages documentation as well. I've met plenty of developers who are thoroughly convinced that the code is the only documentation that anyone would ever need. Here's the problem with that thinking:

      void frob_the_splutnik(int a, int b) {
                  s = get_splutnik()
                  s.frob(a, b)
      }

      That's definitely concise, and perfectly clear, but only if you already know what a splutnik is or why you'd want to frob it, and what a and b are supposed to signify. If you're a developer unfamiliar with this code base though, you have no clue what this means, not because you're dumb but because you've never encountered any of the concepts that the original coder had in mind.

      --
      I am officially gone from /. Long live http://www.soylentnews.com/
    2. Re:Don't Accept by Anonymous Coward · · Score: 1

      Quote from unknown source: It's called peer review only if the developers dislike each other. It's called pair programming otherwise.

    3. Re:Don't Accept by Anonymous Coward · · Score: 0

      Unfortunately documented code often looks like this:

      // this code frobs a sputnik
      void frs(int a, int b) {
      s = get_sp()
      s.fr(a, b)
      }

    4. Re:Don't Accept by Anonymous Coward · · Score: 0

      Which makes matters even worse because the code actually frobs the splutnik not the sputnik

    5. Re:Don't Accept by Aladrin · · Score: 1

      I've heard that before and find it funny, but Pair Programming is actually a step beyond. It includes automatic peer review as part of it's process, but goes further.

      I've personally found PP to be of use in certain circumstances, but generally prefer not to use it. Peer review, however, remains valuable all the time.

      --
      "If you make people think they're thinking, they'll love you; But if you really make them think, they'll hate you." - DM
    6. Re:Don't Accept by Quince+alPillan · · Score: 2

      That's definitely concise, and perfectly clear...

      No it isn't. If you're in an industry where you're frobbing splutniks, you would expect developers to understand why splutniks need frobbing or else they should talk with someone to find out why they need frobbing. That way, through cross-training, you can understand the concept behind frobbing and are better able to utilize it in your code. In addition, a and b are horrible variable names and don't explain what they are and should provide insight into what is involved with the frobbing processes even if you don't know exactly what frobbing is.

      On the other hand, if you're in an industry where you're not commonly frobbing splutniks, you might explain why this splutnik needs frobbing or when you're being clever (such as inside the frobbing algorithm) or non-obvious to someone within the industry. A good rule of thumb might be if your project manager or supervisor can read the code and understand what it's doing.

    7. Re:Don't Accept by b4dc0d3r · · Score: 2

      People who think the code is the documentation would not, in my experience, do something so idiotic. If you work in a domain where everyone is expected to know those terms, it works. If not, you find better variable and function names.

      I always have clearly descriptive names, straight out of programming 101. That's mostly so I don't forget which one is which. The only 1-letter variables are counters, x, c, or i. And usually I use 'count', 'counter', 'index' or something else instead.

      The end result is, the code actually is self-documenting and needs no explanation other than bug fixes or algorithm changes for specific reasons.

    8. Re:Don't Accept by gstoddart · · Score: 1

      frob_the_splutnik ... That's definitely concise, and perfectly clear

      But, it could be a title ... he could be Frob, the Splutnik. :-P

      --
      Lost at C:>. Found at C.
    9. Re:Don't Accept by Anonymous Coward · · Score: 0

      Self documenting code is only useful when it works for ALL cases and there are NO exceptions.

      So if you can prove that ALL splutniks are frobbable and that frob works for all values of A & B then it's not so bad. A and B might not even be terrible variable names if I can easily google "frob" and see that the usual notation for frob is frob(a,b), much like atan(x,y).

      However for the 99% of the time where that is NOT the case and there are exceptions, preconditions, or assumptions then you MUST document them or the next programmer, not armed with your knowledge will frob and unfrobblable splutnik and your program will fail.

    10. Re:Don't Accept by Anonymous Coward · · Score: 0

      And when go-live is in 2 weeks, you get back 3 weeks worth of changes (plus QA), and you absolutely cannot delay or fight the client?

      And this happens once a month because you're 17 developers short and can't seem to get more?

      There's a million reasons to write documentation. There's one good reason not to. The bottom line. It's not worth missing a deadline, losing a client, or paying a fine. And the last thing you want to do in this economy is piss off your developers by telling them they're putting in night or weekend hours to write docs.

    11. Re:Don't Accept by Tablizer · · Score: 1

      It is documented, it's just written in Russian.

    12. Re:Don't Accept by Anonymous Coward · · Score: 0

      [...] but only if you already know what a splutnik is or why you'd want to frob it, and what a and b are supposed to signify.

      That piece of code is not the place to define what "splutnik" or "frob" mean. Definitions for technical or domain terms don't belong sprinkled through code comments.

      "a" and "b" are not self-documenting in any reasonable interpretation.

    13. Re:Don't Accept by olau · · Score: 1

      No explanation for you or for others?

    14. Re:Don't Accept by radtea · · Score: 1

      The end result is, the code actually is self-documenting and needs no explanation...

      ...to the people who wrote it. To everyone else--the maintenance coders, the guys who work for the company that bought the company that bought the company that wrote it--the "self-documenting" code is written in a private language. It may be possible to figure out what it's doing, but not why. Since engineering choices are never simple either/or code is full of trade-offs and the reasoning behind those trade-offs needs to be documented to it can be taken into account by people down the line. Otherwise they will at best waste time reinventing the wheel and at worst make design decisions based on incorrect guesses about the original intent.

      You might as well claim that an engine is "self-documenting" because it is obvious that you've used 1/4-inch NF machine screws to hold a part in place. What isn't obvious is why you have done so.

      --
      Blasphemy is a human right. Blasphemophobia kills.
    15. Re:Don't Accept by istartedi · · Score: 1

      Today I learned that "splutnik" is screen, and "frob" is plot. I think the function would be better if it returned an int to indicated that you attempted to frob outside the bounds of the splutnik.

      --
      For all intensive purposes, "whom" is no longer a word. That begs the question, "who cares"?
  11. As they say.. by Anonymous Coward · · Score: 0

    Don't document your code. But code your documentation.

    Apart that, i disagree on the 'financial' motive as suggested. The real solution is to reduce the pressure. Increasing pressure by putting a bounty will slap back in your face in the long run. And hard.

  12. Realistic Deadlines by Anonymous Coward · · Score: 0

    Being realistic about the deadlines goes a long way to getting developers to do their commenting as they go. If your developers are having to work 50+ hour weeks to get the code out of the door as it is then there really isn't much of an incentive for them to add to their workload, no matter how big your carrot or stick as there comes a point where no amount of money can replace having a life outside of work.

    Make sure your quotes contain adequate time to both write and document the code and don't expect the developers to pick up the slack with their free time.

    1. Re:Realistic Deadlines by delinear · · Score: 1

      Exactly this. In a lot of instances the best case scenario is that the project timeline already tries to squeeze too much development into too little time, so even to hit the initial deadline for just producing the raw code you're still reliant on developers working over on their own time. To those who suggest incentivising with money, a better idea would be to use that money to take on another developer and spread the work so that the deadlines aren't always insanely tight (though in reality the second another developer is hired either the timeline will shorten or the workload will be increased).

  13. I've done it. All of it. by vikingpower · · Score: 1

    From the incentives and the carrot to the stick. Yet - as soon as I had my back turned, were I a team leader or a consultant or whatever, they went on developing - without documenting. It seems a near-impossible task.

    --
    Religous speak to God. Insane are spoken to by God. When all shut up, one can finally hear Shostakovich in peace
    1. Re:I've done it. All of it. by Anonymous Coward · · Score: 0

      Yeah, duh, if you drop the incentives.
      For us as programmers the situation is usually like this: a project has to be up and running by insane date X. Managers never turn their backs on this, and keep the stick on a pedestal outside their office.
      If you want your programmers to document their code, give them the time and incentive they need. This is a classic case of "you get what you pay for"; if you "turn your back" (i.e. remove the time and incentives) your programmers simply cannot afford to continue documenting their code.

  14. Time... by Anonymous Coward · · Score: 0

    How about managers allow sufficient to write documentation? (Instead of "get it out the door")

  15. Recursive Logic by jrq · · Score: 2, Funny

    As I used to say "it was damn difficult to write, it should be bloody difficult to understand".

    --
    My UID is prime!
    1. Re:Recursive Logic by Migala77 · · Score: 1

      As I used to say "it was damn difficult to write, it should be bloody difficult to understand".

      used to say when you still had a job?

    2. Re:Recursive Logic by jrq · · Score: 1

      Yes. I when I still had that, AND a job.

      --
      My UID is prime!
  16. Documentation not always worth it by DoofusOfDeath · · Score: 4, Interesting

    I'm growing increasingly convinced that in many situations, code only requires a minimal amount of documentation.

    Code under development changes rapidly, so most of that documentation would never get used. And lots of code is best explained by the code itself plus small, local comments, rather than by separate, copious documentation. And then there's the fact that software often gets discarded before anyone would need to make the kinds of modifications that required extensive documentation.

    It seems like sometimes, people who call for extensive documentation do so from the intuition that it's a diligent, long-term-smart strategy. I think the picture is muddier than that.

    1. Re:Documentation not always worth it by Tom · · Score: 1

      Agree to that in parts. Here's the parts:

      a) If you need documentation to understand what the code does except for complex formulas or dirty tricks, you shouldn't be reading my code, much less maintaining it, period. Yes, if I have some math that fills several lines, I'd better put a sentence or two there explaining what it means. But if for anything like creating an object, assigning some values, calling a few methods, storing the result in the database, displaying the result, etc. etc. - if I need to write documentation for anything like that, then either my code totally sucks and is a ton more complicated then it needs to, or whoever is in need of the docs is an idiot who shouldn't be touching code. Sure, "foreach ($row as $key=>$val) { $$key = $val; }" - could be graced with a one-line comment explaining what it does. But if you can't figure it out just by reading the code, then really, get your hands off it, you are more likely to break than fix it.

      b) What needs documentation is the relations between code pieces, especially on the inverse side. Good IDEs can cover a part of that, but never completely.

      c) Logic needs documentation. "if ($value > 10) { ..." has exactly one information that I can't understand purely from reading the code: Why 10? Why not 11 or 9 or -512? What does this number mean and why is it hardcoded?

      d) Documentation is worse than worthless if nobody keeps it updated. If your code is changing over time, and you can not guarantee the the documentation will be current, you are probably better off without than with outdated.

      --
      Assorted stuff I do sometimes: Lemuria.org
    2. Re:Documentation not always worth it by teh+kurisu · · Score: 1

      I think you need some form of document that pulls together your entire project, and explains how all the parts fit together. And each part needs to have an executive summary, to explain what it's meant to do.

      I don't think line-by-line comments are all that valuable, unless you're doing something odd that really does need explanation. Sometimes I find that they make the code more difficult to read, not less. Especially where the comment lines outnumber the lines of code.

    3. Re:Documentation not always worth it by Anonymous Coward · · Score: 0

      I agree and disagree with this. I agree that comments and code can really help the next guy. However, I believe they should be used in copious amounts, whereas you seem to be suggesting only the occasional small comment. The more information the merrier in my opinion. Also, separate documentation, especially charts, and really help. I hate making those charts of course, but I see their usefulness. Can you really make all that documentation and still deliver in a timely fashion though? With comments yes because it doesn't break your personal groove, charts I don't believe so because it forces you to stop coding and switch contexts. There is an old saying that I think is applicable to this situation, you can have it fast, have it of high quality, or have it cheap pick two.

      Having said that. If you leave behind a sentence explaining what a line of code does, someone who doesn't grasp why you did something the way you did will have a better idea of the intention of that line. If you try to do this for each and every seemingly obvious line of code you'll quickly find that someone glancing over your code, or even yourself glancing over old code, that you or they now have a better understanding of that code.

      For the record, I find the GhostDoc plugin for Visual Studio pretty useful. I don't simply use it to generate some meaningless boiler plate documentation, I always add additional sentences and alter the existing ones. But, it helps motivate me to document variables and methods that I might have otherwise avoided. Basically, it gets the ball rolling for me and avoid procrastinating on the writing of comments. I've also gotten myself into the habit of doing two additional steps. Before I write a method, I create the method stub and jot various lines of // TODO: comments, and once I've implemented the code for those lines I simply remove the TODO: text but leave the original comment there. I may also adjust the sentence if I ended up implementing the todo slightly different. The second step I take is that any new lines I write, I always write the comment for what they intend to do first. If I'm glancing over my own code and I notice that I haven't documented a line, I read what it is doing and I write up a quick comment.

      I do all of this even if I feel the line is obvious by itself, it's a rule I've been holding myself to. Because, sometimes what's obvious to you at the time isn't always obvious to others.

      Sometimes I leave behind comments that warn the programmer, or tell them the reasoning we had to do something a certain way. Especially if it looks like the piece of code could be optimized, but that the reason the piece of code exists was to solve a defect for the customer and naive optimizing, refactoring, or altering its functionality would reintroduce the defect.

    4. Re:Documentation not always worth it by Anonymous Coward · · Score: 0

      I agree 100%.

      Plus give me well structured and formatted (and "self documenting") code but sparsely commented code any day over messy code with lots of comments (and often with unneeded complexity).

      Plus what guarantee is there that the comments will accurately reflect what the code is actually doing? If you have to look a the code anyways then the comments can be just added distraction.

      I use comments to explain cases where on first glance the code might appear to be non intuitive or deviate from the seemingly "obvious" way of doing something.

      And I have a horrible memory. So I write the code to be able to be maintained as easily as possible when I have to make changes down the road long after I have forgotten my original intentions and methodology. And this translates into someone else being able to easily maintain the code as well.

  17. Code Reviews and include in Job Description by realsilly · · Score: 2

    If you warn a developer up front that documentation of code is part of the job and you let them know there will be random code reviews they can't complain when they see no merit pay increases or eventually are laid off for now performing as expected. If a company does not allow for adequate time to have developers document code during a project it's the companies own fault, period.

    Developers have been told time and time again through-out the last 20-30 years that documenting your code is good coding practice, but a vast majority don't. There are several reasons, and the one I hate worst of all is the "job security" response. Be honest, you don't want to so you don't.

    --
    Life takes interesting turns, but the most interest is when you're off the beaten path.
    1. Re:Code Reviews and include in Job Description by L4t3r4lu5 · · Score: 1

      Be honest, you don't want to lose your job while your well documented code is shipped to an Indian man-farm in a cost-saving (read: Bonus increasing) exercise, so you don't.

      Y'all made your bed.

      --
      Finally had enough. Come see us over at https://soylentnews.org/
    2. Re:Code Reviews and include in Job Description by delinear · · Score: 1

      Be honest, you don't want to so you don't.

      On the contrary, a lot of developers would like to document their code (particularly if they have found a rather elegant solution to a tricky issue - everyone likes the opportunity to show off a little at a job well done). Having worked enough 90 hour weeks on projects to last me a lifetime I can tell you that it's never going to happen. You can't get blood from a stone and you can't give people zero time to do a task when they're already gifting you time over and above their 40 hours for free and yet habitually expect that task to be done.

  18. Surely I'm not the only one by AdrianKemp · · Score: 3, Interesting

    I've never had a problem of incentive or motivation to document my code; my problem is and always has been time.

    Documenting anything other than conceptual stuff from the beginning is a bit of a waste (though far from a complete one) because the final product (due to bug fixes/spec changes/etc) never matches what you set out to do.

    So when you do get to the point of post-testing where the code has stabilized and it's time to really sit down and document everything fully you're being given new stuff to work on. Sure I can (and do) raise a bit of a fuss about it and explain that if it doesn't get documented *now* it'll never get documented *well*. That always seems to fall on deaf ears though.

    I think a lot of it is that the deserved biting in the ass never comes. Shortened product life cycles and customers that have become (wrongly) more tolerant of buggy software in production environments means that you can stumble through with a vague knowledge of the product and never really get fucked. It's the same basic reason that so many bad programmers have jobs.

    1. Re:Surely I'm not the only one by Assmasher · · Score: 2

      This is why you "document your code" as you write it.

      There's no reason you can't document your code as it is being written, in fact, it's the best time to do it because the documenting the *reason* you choose to do something a particular way can actually be more important than ensuring that the following code is easy to follow.

      There are, of course, limits to what you should document in code. For example, I wrote a software renderer in Java two years ago and there is a section that relies on some hidden surface removal techniques covered well in Abrash's book(s) but very complicated to explain in the level of detail that any software engineer would understand because explaining it relied on a corpus of knowledge not common to software engineers. My documentation in the code explained it rudimentarily and then pointed anyone else reading it to some references for greater understanding. That was the one place in the code I did that, and it was the first time I've done that in code comments before.

      BTW, it is quite often more valuable to give your variables and arguments clear names that intimate their usage and intent than over the top code commenting - but it all helps.

      float[][] m_aHiddenSurfaceRemovalScanlineFragments_Z;

      is much more clear than

      float[][] m_aHSRFragsZ;

      (Ignoring our Hungarian notation approach of course)

      BTW, names like that can be a lot of typing, so we usually write, build, test, validate, refactor for clarity, then check-in.

      --
      Loading...
    2. Re:Surely I'm not the only one by AdrianKemp · · Score: 1

      I'm not sure how what you wrote is in any way a reply to me... but there are better spots to reply off topic to get higher on the page so I'll assume you actually think what you wrote had something to do with what I did.

      Nowhere in my post did I ever say anything about not commenting code. The article is not about commenting code it is about documenting code. If you do not know the difference between those two things, please learn it before writing another line.

    3. Re:Surely I'm not the only one by Assmasher · · Score: 1

      Try not being a sanctimonius ass.

      Documenting your code is a multi-part process, including comments in your code; unless, of course, you'd like to argue that putting proper comments in your code is not part of documenting your code at all...

      Let's break this process down for you since you seem to think it is a one aspect problem.

      This process works in smaller iterative cycles for some teams, in larger iterative cycles for some teams, and in a monolithic cycle for some teams. Some teams aggregate Requirements Gathering and Specification writing.

      (1)Requirements gathering - Nothing to do with documenting code
      (2)Specification writing - Nothing to do with documenting code
      (3)Design writing - Part of documenting code
      (4)Implementation comments - Part of documenting code
      (5)Updating design - Part of documenting code

      You claim that you don't have time to do #3 or #5.

      That's because you're acting like a programmer, not a software engineer.

      If your pre-implementation designs are so different from your end results, the problem isn't that you don't have time to document properly, the problem is that you design poorly. If those designs change due to external influences (such as changing specifications/requirements) then the problem isn't that you don't have time to document properly, the problem is that you handle your customers poorly.

      You want to argue that proper documentation doesn't have anything to do with code commenting? Well, let's just hope you stay a programmer then because code documentation's purpose is to, bluntly, give your company/employer/client a way to continue when you stupidly walk in front of a bus.

      The majority of the benefit is in well commented (to differentiate for you since you would interpret documented to be external documents) code. Architectural overviews are valuable, but trivial to write and maintain. High level feature documentation should happen in both external documentation and in the code base. Low level feature documentation of code should not be in an external document, but primarily just in the code unless it is something extraoridinary (such as an obscure 3D rasterization optimization technique from the early 90's that you had to use for some reason.)

      Please learn to be a software engineer "before writing another line."

      --
      Loading...
    4. Re:Surely I'm not the only one by AdrianKemp · · Score: 1

      You're a moron (this is no surprised based on your first post)

      You honestly believe that the only documentation for code is commenting; and that is enough to prove your idiocy... we'll continue anyways.

      I never made (most of) the claims you attribute to me; I very clearly stated that conceptual design documentation is a bit of a waste of time (once you already have RFCs and specifications) though not a complete one. I did not anywhere say I didn't have time for it or that I didn't do it. What I did say was that it doesn't reflect the final product; it never does.

      Based on your crack-pottery about initial design vs. end result you've clearly never worked anywhere so we can dismiss that point entirely.

      Your second point is based solely on the fact that you don't know anything beyond commenting code. commenting is not documentation and if you're putting actual documentation in comments anyone that ever sees your code is going to murder you.

      Your third point is in complete contrast to your first two and just cements your status as the village idiot.

      Comments are most useful (based on an anecdotal survey of everyone I've ever worked with) for confusing bits of code. If something doesn't make sense at a glance comments are pure gold for resolving it. If you have no idea what any of the code does you shouldn't be expecting comments to enlighten you; that's what documentation is for. Just as you wouldn't expect tooltips to teach you all of the features of a program; that's what documentation is for.

    5. Re:Surely I'm not the only one by Assmasher · · Score: 1

      Wow, not only are you a poor software engineer (if even that) - you're a liar as well.

      "You honestly believe that the only documentation for code is commenting" - Really? Despite my posting the following?

      (3)Design writing - Part of documenting code
      (4)Implementation comments - Part of documenting code
      (5)Updating design - Part of documenting code

      Followed by dishonesty about what you yourself posted:

      I did not anywhere say I didn't have time for it...

      Funny, if your first post you state, clearly (perhaps not clearly enough for yourself):

      I've never had a problem of incentive or motivation to document my code; my problem is and always has been time

      Never worked anywhere? LOL.

      I've been directly involved in the leadership of architecture and development for more than 5 companies - 3 of which were sold to for more than 60 *million* dollars (aggregated startup costs of less than 10 million dollars.)

      I own my own ISV startup currently, and I am also simultaneously the CTO of another successful ISV. I'm also on the advisory board to a large private equity firm as their technical resource and I perform all of their technical due diligences.

      Needless to say, statistically speaking I am *likely* to be much more experienced and battle tested software engineer than yourself, kid...

      Your third point is in complete contrast to your first two and just cements your status as the village idiot.

      Funny, perhaps you should provide quotes so people have some idea what you're referring to here - I don't want to spend anymore time than necessary pointing out you flailing inadequecies as an "engineer."

      I'm happy to hear that you've performed an "anecdotal survey" of everyone you've ever worked with at the "Code Academy."

      --
      Loading...
    6. Re:Surely I'm not the only one by AdrianKemp · · Score: 1

      I'd post an actual reply, but you've done more to damage your credibility than I ever could.

    7. Re:Surely I'm not the only one by Assmasher · · Score: 1

      I'm sure that's why - lol...

      --
      Loading...
  19. What carrot? by TrashGod · · Score: 1

    A break from weekend or late-night on-call duties if they volunteer? Sounds like an great way to demoralize the (fewer) remaining workers who must share the (unchanged) burden.

  20. Anatomy of a documented method by Ouija · · Score: 4, Insightful

    // WHY
    int WHAT(...) {
          return HOW();
    }

    --

    -Ouija- poke 53280,11:poke 53281,12
    1. Re:Anatomy of a documented method by marcosdumay · · Score: 1

      Well, there is something I don't understand here.

      Why do people keep talking about comments when using the word "documentation"? Do they only document APIs? Because that is the only thing autodoc is usefull for.

      You need that why, but it doesn't belong to the code. That why belongs to the business model, or the use cases. In no way somebody wearing a developer (or software engineer) hat should be in charge of writting it (ok , he can write, but only after somebody with another kind of hat dictates for him).

      Then, your code is left to follow that template: // Long WHAT (if applicable)
      int WHAT(...){
              return HOW();
      }

  21. too much formulaic crap by dltaylor · · Score: 2

    I write comments when what I'm doing is "clever", or hardware-required. Otherwise, I use meaningful labels and a readable syntax (C, for example, is K&R, except that all block-opening braces are on the next line for easy "line-up", any code beyond the current line has braces; variables have meaningful, not formulaic, names).

    Too many managers and "religious" programmers want forty lines of comments for a twelve-line function. They ain't getting it from me, and, so far, my peers are happy with what I do. I comment shell scripts, PHP, Perl (more than the others), ... when there's a real reason, not just to fill out some silly "comments requirement". I put useful comments in svn checkins, too. Those are probably more meaningful than most of the code comments I have seen.

  22. Give 'em incentives by El+Solitario · · Score: 1

    During my whole career I have been at least extensively inline-documenting the code I produced and got nothing absolutely nothing in return, if not trouble for not meeting a deadline that was poorly planned ahead of production anyway. Sure, extending deadlines somewhat is part of the business, but having a boss breathing down your neck despite knowing you wont be able to meet a deadline does not help, but I digress. My point is that if you do your job properly, which includes developer-readable inline documentation as well client facing docs, you should get something in return for devalorizing yourself as "IP asset". Be it extra cash, time off or at very least a pat on the back.

  23. We already know the answer. by sidragon.net · · Score: 1

    But we also know that nobody here or their managers are going to accept it and follow through, so why bother having the discussion?

    1. Re:We already know the answer. by geekoid · · Score: 1

      Because you are wrong. many people follow through.

      I comment, and I demand other programmers do so.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  24. Ah, I know the answer to this... by 3seas · · Score: 1

    You want it When?

    On another note, coders that define the coding intent/objective first, in terms of coding (not client view) will have a skeleton of documentation to work from and their code may even be cleaner.

    What is coding anyway, but the automation of images of human thought processes to be run on a a stone of minerals. So its really just a task of translation from human language to something a computer can process accordingly.

  25. It's all time and pressure by Anonymous Coward · · Score: 0

    IME, few places value well-documented code. There is usually a tight schedule and some unexpected changes. (Yeah, Agile is supposed to fix this, but comments don't pay the bills, so there's always business pressure to just do the code). Add to that the threat of outsourcing, done badly ( as most American companies do it), and there is little upside to well-documented code to a developer in the trenches.

    As for making it easier to debug and deal with support issues, well, those are not development costs in most companies, so they are not in the discussion.

  26. Real answer not the BS answers they give.... by Lumpy · · Score: 1

    You want us to document our code? then GIVE US TIME TO DO SO.

    Documentation takes time, I cant do it magically.

    --
    Do not look at laser with remaining good eye.
    1. Re:Real answer not the BS answers they give.... by mcavic · · Score: 1

      Yes, this. When you have 3 projects going on at once...

  27. next to relevant by Tim4444 · · Score: 1

    Nice. Right after Hostess files for bankruptcy TFA cites "hacker machismo" with a link to a list of "real programmer" attributes which includes 'surviving on Twinkies'. Seems like there's not much demand for that "food" after all.

  28. Re:Documentation is usually worthless by CadentOrange · · Score: 0
    I would go so far as saying that documentation of non-public APIs (i.e. stuff that is only used by the same team) is worthless as it rapidly gets out of date, and it takes an insane amount of effort to keep it up to date and correct.

    Keeping the documentation up to date requires additional effort and time, which means less time for writing code and unit tests. This much is self-evident as is the result: each piece of work takes longer to deliver.

    Ensuring the documentation is correct and up-to-date is impossible. There are loads of tools that will help you improve the quality of your code. Static analysis tools, unit tests and code coverage tools, and the good old QA department to name a few. No such tools exist to ensure the quality of your documentation. Additionally, as documentation does not get executed as part of the build/unit-tests/QA tests there is no way of ensuring that the documentation isn't flat out wrong (nevermind ensuring that the documentation is "correct").

    On most projects, sensible class/method/variable names help reduce the need for documentation. Properly written, comprehensive unit test coverage all but eliminates the need for documentation. Want to know how to invoke a particular piece of code? Look at the unit tests. Want to know what this option does? Look at the unit tests. Want to know the behaviour of a piece of code given a certain parameter? Look at the unit tests. Want to know all possible values for a parameter? Look at the unit tests.

    The only time you ever want to have comments is to explain what a piece of non-trivial, non-intuitive piece of code does.

    TLDR version, properly unit tested code rarely ever requires accompanying documentation. The fact that the author of the article FAILS to mention unit tests just shows that he's spent far too little time writing code and far too much time writing stupid fluff pieces like this for PHBs.

  29. Management problem, not programmer problem by Dcnjoe60 · · Score: 1

    Lack of documentation of code is a management problem. Management tends to have unrealistic timelines for development, without enough slack time built in. Documenting code takes a back seat when deadlines are looming. If adequately documenting code takes 10%-20% of the time to actually code, then timelines need to be extended accordingly. That is usually unacceptable in today's environment where corporate management takes the approach of get it out the door now, we'll fix it later.

  30. design document vs. documenting source code? by us7892 · · Score: 3, Interesting

    I've found two camps at my company. Both camps document their code with comments and meaningful commentary. It is more a matter of the "design document" that describes the product or project that is a problem. The document that is perhaps supposed to guide the overall architecture of the product, and thus, the architecture of the classes, methods, interfaces, etc., aka. "the code".

    The first camp of developers just wants to get in and start coding. They often say "I need to code to figure it out." The actual web site works well, but new developers have a tough time maintaining that same site. The original developers are pretty much the only ones that can change the critical aspects of the site, and even then, as time goes by, that becomes difficult. But, they got the site up and live in the time allotted. And they wrote a 2 page "design document" when they were done - the doc was useless.

    The second camp of developers writes a 50 page design, then starts coding. The actual web site works well, but the overall time to get the site up and live took 5 times longer (that includes the time to document.) The documentation evolved with the changes that were made along the way. Maintaining this same site went well at first, since the documentation was great. But, the docs slowly get neglected, and in a couple years, this site is difficult to maintain.

    In the end, perhaps there is a happy medium. A "good enough" design document, and get started coding relatively soon. I used to lean toward the second camp, but now I lean toward the first camp :)

    1. Re:design document vs. documenting source code? by mandelbr0t · · Score: 1

      I used to lean toward the second camp, but now I lean toward the first camp :)

      Glad to hear it. I'm the first to admit that I don't always document well enough, but I'm a build-it-then-fix-it kind of guy. I've been at it long enough to get an extensible architecture off the ground right away. I'd work better with someone that's a get-it-right-the-first-time kind of guy telling me what I'm doing wrong, though.

      --
      "Please describe the scientific nature of the 'whammy'" - Agent Scully
  31. Easy Math by Anonymous Coward · · Score: 0

    If a project should cost me 8 hours to do well and 1 hour to document and you give me 4 hours to finish it, you get bad undocumented code.

    1. Re:Easy Math by Kagetsuki · · Score: 1

      I had to bail someone out -just yesterday- and the conditions were this example to the letter. The code wasn't "bad" but it wasn't perfect and certainly not something I'd like to admit to writing. It had precisely 0 comments. If documentation was a requirement I'm certain I would not have finished at all.

    2. Re:Easy Math by geekoid · · Score: 1

      A) had it been commented, it would have been easier
      B) A comment should take a few second. If you are taking an hour for every 8 hours of code for commenting, then you are doing it wrong.

      At least the next poor sap will ALSO have to take longer to change something because you didn't comment it either.

      You people are just making excuse for being sloppy.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  32. Waste of time by Yuioup · · Score: 1

    Documentation is a waste of time. You're better off writing your code cleanly so that somebody else can decipher it easily.

  33. The problem isn't the "programmers" it's managers by Assmasher · · Score: 1

    Most managers don't understand that they need proper code documentation (much less what "proper documentation" actually is), architectural documents, design documents, et cetera. They only realize it when it is too late and they need it. Then they blame the programmers.

    Now, I don't expect much out of a "programmer" personally. A "software engineer", however, I DO expect better from.

    A software engineer shouldn't have to be told how to do their job properly.

    --
    Loading...
  34. It's A Question of Honor by Gallenod · · Score: 2

    "What!?! Comment my code? You question my honor! I'll kill you where you stand!"
    -- Mukluk, Klingon Programmer

    --

    TLR

    A man no more knows his destiny than a tea leaf knows the history of the East India Company
  35. Fire them if they don't by echusarcana · · Score: 1

    No comments. No paycheck. It is pretty simple.

    1. Re:Fire them if they don't by BVis · · Score: 3, Insightful

      I hope to $deity you're not a manager. Your morale must be terrible if you do.

      I have to echo other commenters: If you want well documented code, you need to allow sufficient time for said documentation to be written. Failure to do so isn't a failure in programming, it's a failure by management to build realistic timelines based on feedback from programmers.

      If your programmers are constantly telling you they need more time, on project after project after project, and it's ALL of them, not just a few complainers, then you need to look in the mirror to find the source of the problem. Go to sales/marketing, read them the riot act about promising impossible deadlines, and get THEM fired if they continue to promise unicorns on a wombat budget.

      --
      Never underestimate the power of stupid people in large groups.
    2. Re:Fire them if they don't by Anonymous Coward · · Score: 0

      I'm one of the few programmers saying I need more time.

      I have one co-worker who documents, but their cute comments and don't tell why he did something. Others don't document their code.

      I'm trying to introduce software patterns as a way of introducing some common structure and some common vocabulary. It will be incomplete, but since we support about ~20 business units in a large enterprise, there will always be a bit of variety. I just want to start having common code where we have common tasks.

      I don't have sales, marketing, et al to worry about, its only my boss who sets deadlines. Ocassionally, we'll have a real hard deadline (for example, we are outsourcing a system, so we need to have all of our processes and other systems which query it updated by a specific date since that's when its being outsourced) but they are really rare.

      If I write test code, they assume they gave me too much time. If I write documentation, I get thanked, but again they assume I could have done it in less time. Most of my co-workers just don't get it; I have been given above average raises every year (not much since I still don't make the average starting salary for my degree) and my co-workers do seek me out as an expert who can help them, so I honestly beileve I am going down a good path, but its definiately a struggle. Luckily PCI has helped us get some of the security best practices I've been wanting.

    3. Re:Fire them if they don't by echusarcana · · Score: 1
      I am actually a manager. And a programmer for 30 years too so I am pretty good at judging how much time any project will take. And I *have* gotten people let go because of poor documentation.

      Written (separate) documentation largely depends on the situation. In my observation is is not that useful and even when produced it does not get read. However, code commenting is essential. A competent programmer should by writing it along with the code.

      I've seen a number of programmers leave out documentation because they perceived it as job security. I've even seen programmers DELETE comments that were already existing in other's work.

      Bottom line is if you don't comment on my watch, I will fire your ass.

  36. Easy! by Anonymous Coward · · Score: 0

    I use only documented technologies.

    Example: The whole Typo3 documentation could be thrown away if they had used XSL instead of doing their own thing.

    1) End user asks me something
    2) I spit out a link
    3) ...
    4) End user GTFO

    Easy!

  37. I love documents... question documenting code by scamper_22 · · Score: 1

    I'm in odd developer in that I love documenting. I'm known for my extensive user guides, wikis...

    However, I've never spent much time documenting code itself. Most code should be readable on its own. Good variable names, well named functions, well separated classes...

    About the only useful in code documentation is if for a API that you plan to have proper javadoc or something.

    But again, far more important than in code comments is documenting the big picture of how the application works. I'm big on diagrams and block diagrams... and I'm not going to do that in ascii :P So they normally end up on a wiki.

    Finally there's the issue of time. There's a lot of things we *should* do, but we don't have the staff or the time.
    Documenting code itself is pretty far down that list of things I would prioritize.

    1. Re:I love documents... question documenting code by geekoid · · Score: 1

      " Most code should be readable on its own. "
      that was wrong 25 years ago, and it's wrong today.

      It is not possible. You need to tell why the function was made. You can't dictate that accurate through just code.

      How do I know something is wrong if I assume everything you wrote is doing what it is suppose to because it's 'self documenting'?

      and yes, use clear names.

      "Documenting code itself is pretty far down that list of things I would prioritize."
      then you are just wasting more of the company time. and code documenting should never take more then 30 seconds for a new procedure, so not a lot of time at all. And 30 seconds is gererous. //Calculate arrival time for ship

      Now I know what the programmer is trying to do. SO when I see they are calling a function that assumes no movement on a holiday, I can immediately see what the problem is, even if I am just reviewing the code.

      Yeah, I hear the 'there isn't any time' argument. Usually by people who came to my cube to take 5 minutes to bitch about who shot whom first in some Sci-Fi show.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
    2. Re:I love documents... question documenting code by scamper_22 · · Score: 1

      //calculate arrival time

      should be its own function :P

    3. Re:I love documents... question documenting code by nschubach · · Score: 1

      //Calculate arrival time for ship

      How is that different from...
      class Ship extends Container {
            public function getArrivalTime() {...}
      }
      Do you really need to comment that that method of Ship Container returns the calculated arrival time?

      --
      Every time I start to have faith in humanity, I ruin it by driving to work between 7 and 8 am.
  38. Pair programming? by Anonymous Coward · · Score: 0

    Have you tried pair programming? Having multiple programmers working on a same code means that they need to coordinate. They get to talk/write down stuff for each other. It is even better if programmers are separated by a few time zones ... after you are woken up at 3am by a phone call just because some simple stuff wasn't documented, you will preemptively document staff.

  39. Docuentation Managers? by StewBaby2005 · · Score: 1

    What happened to peer code reviews? Maybe it;s not 'quick' or 'agile', or 'extremee', but a code review is where you tell the programmer "You need better comments in here. etc. etc"

  40. Literate Programming as opposed to Illiterate by WillAdams · · Score: 1

    Send your programmers this link:

    http://www.literateprogramming.com/

    and have them read this book:

    http://www.amazon.com/Literate-Programming-Center-Language-Information/dp/0937073806/ref=sr_1_1?ie=UTF8&qid=1326462347&sr=8-1

    ``Propaganda'' here:

    http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html

    I re-wrote the typesetting back-end of an interactive, graphical ad design / generation program as a literate program and it made a _huge_ difference in the maintainability of the system and made adding additional features _much_ easier.

    --
    Sphinx of black quartz, judge my vow.
    1. Re:Literate Programming as opposed to Illiterate by samjam · · Score: 1

      Yup; literate programming is the way. I wrote fangle, a literate untanger for texmac, and for lyx.

      http://www.nongnu.org/fangle/

      I use it for my daily job.

      Literate programming means that instead of commenting your code (or feeling guilty for not doing so) you code your comments. Or rather you write a book about the problem your program solves, and in the narrative of the book you introduce aspects of code that solve the problem. As you do this you slowly reveal the solution - a well documented solution!

      No-one is forced to use it, my replacement (when the day comes) can just edit the generated source if they want.

      Also consider Mylyn Intent for Eclipse Java coding if you like that sort of thing.

    2. Re:Literate Programming as opposed to Illiterate by flargleblarg · · Score: 0

      Sam— Your comment "Literate programming means that instead of commenting your code (or feeling guilty for not doing so) you code your comments." is probably the best LP quote I've ever heard. Is that your own original sentence? I'm bookmarking it so I can quote you on it sometime, but I want to make sure I have the attribution correct.

  41. Tell Them Other People Will See It by Cryophallion · · Score: 1

    Tell them that they will open source the code with their name pegged to it. Better yet, tell them you will send it to their college professors and any company that calls asking for employment verification...

    I write a very small codebase, but it is used in webpages, so I know that others will see it. The embarrassment of ugly and badly commented code alone makes me keep my documentation up to date.

  42. And BTW this is not documentation by nirgle · · Score: 1

    // Close the stream
    stream.Close();

  43. Catch 22 by Kjella · · Score: 2

    Documentation doesn't really have all that much value unless you can trust it, and in a large organization with a large code base there's likely to be code where the documentation is incomplete, inaccurate or plain old outdated and wrong. Once you cease trusting the comments and realize you must read the code to actually be sure what it does it turns into an evil circle. Nobody bothers to look at the documentation because it's useless and because it's useless nobody bothers to fix the documentation. And you fixing a few snippets here and there isn't going to change that perception and break that circle.

    Like with structured code it's a lot easier to trash a code base than it is to keep it clean. You can apply a quick fix to the code and it works, but as you get layers or layers of hacks and quick fixes it grinds to a halt. For a time nobody's going to realize the documentation is deteriorating either, it's only as people lose more and more grip on what's going on - usually after key people left - that you're now spending more and more time locating the problem. And since there's no clear system to things, you keep adding more hacks.

    Lack of documentation is just another form of technical debt, and like the entire economy we like to push that debt ahead of us. Maybe next week you'll get another job or get downsized or get outsourced or management will decide to replace it with a different tool or you'll be promoted or reorganized so it's no longer your problem. Meeting deadlines or performance goals now is more important than maintenance later. And your manager, well he's probably got no longer perspective than you, make the executives happy, collect a good paycheck, get a good reference.

    Actually it seems a miracle that we produce software that keeps working, because it doesn't seem like much of anyone is in it for the long term. Workers care about their performance and keeping their jobs this quarter, CEOs and stock holders care about the stock price this quarter and that goes for most people in between. Documentation is cost and nobody wants to take the cost in this quarter if they can take it in next quarter. I've seen companies work extremely hard to get income booked in the current quarter or FY, not because of the two days but because of bonuses and such.

    --
    Live today, because you never know what tomorrow brings
  44. Simple solution by msobkow · · Score: 2

    Make time in the schedule to do the documentation.

    When you're already working a 50-60 hour week just to get something out the door because some moron cut your estimate in half before promising a delivery date, where are you supposed to find the TIME to document instead of code, test, and ship?

    Programmers may hate doing documentation, but it's MANAGEMENT's fault it doesn't get done. Period.

    --
    I do not fail; I succeed at finding out what does not work.
  45. I disagree by acomj · · Score: 4, Insightful

    As someone who's started a new position and using classes with No comments, I can say I've wasted a good deal of time trying to figure out what certain public methods and certain classes do. They've used good naming conventions, but even so there is some subtly about what is done that could have used some explaining, plus looking through 1000s of lines of code before using a method isn't time effective. Its would be far easier for me to read through method header with inputs/outputs than to slog through code trying to figure out if this is the method I want. I don't want every line commented (I've seen that some placws), just the jist .

    I came from an internal api writing group, and those using our code would just ask us questions if they couldn't figure stuff out, and we rsther they didn't so we documented ..

    Examples or some test code I agree are super useful.

  46. Don't document your code ! by eulernet · · Score: 2

    As an agile developer, I recommend against documenting your code.

    You need to document the algorithms, but never the code.

    Documenting your code will require you a lot of maintenance. Every time you change your code, you need to change your documentation. It's a never-ending process.

    Instead, decide on a meaningful notation for your routines names (so any coder knows what the routine is supposed to do), and write tests, or more exactly functional tests.
    Tests have a few goals:
    1) check that your code behaves as expected.
    Suppose that you have to fix a bug in your code, without tests, you cannot be sure that the fix will not be harmful.
    It also allows greater flexibility in your code, and it will not smell like a rotting corpse.
    2) show how to call your code, in order to get results. Examples are very useful for other developers.
    3) confirm a behaviour. Your code does something, but sometimes, it's not clear. Your test should demonstrate the value of your code.
    4) improve the stability of your program, and reduce the QA time.

    Once the habit of writing tests is acquired, you'll start writing the tests before the code.
    This is called TDD (Test Driven Development), and helps reduce a lot the amount of code you need to write, because you only write useful code.
    Who wants to write unused tested code ?

    1. Re:Don't document your code ! by Anonymous Coward · · Score: 0

      Bzzzt. Wrong.

      Here are two methods with meaningful names as part of a class that keeps a list of some sort of data, let's say employee info.

      class EmployeeInfoList {
      public:
      EmployeeInfo();
      void AddRecord(Record *someRecordToAdd);
      int GetIndexOfRecordByName(const char * name);
      };

      According to you those methods don't need commenting, so please PROVE to me whether or not the following code is an error:

      EmployeeInfoList list;
      Record *newRecord = new Record("Bob Smith");
      list.AddRecord(newRecord);
      delete newRecord;

      Short answer, is you can't. You don't know if EmployeeInfoList does a shallow or deep copy of Record in AddRecord. You don't know if it's valid to insert the same info twice:

      Record *newRecord = new Record("Bob Smith");
      list.AddRecord(newRecord);
      list.AddRecord(newRecord);

      or how about this?

      Record *newRecord 1= new Record("Bob Smith");
      Record *newRecord 2= new Record("Bob Smith");
      list.AddRecord(newRecord1);
      list.AddRecord(newRecord2);

      But if your interface signature was properly defined with a formal contract you would know how to invoke it in a way that guarantees there is no bug. So if your list may not contain duplicate entries, you would add a class invariant that states that as part of the contract and test the invariant every time you access the class with a public method. Then when the next developer comes along and tries to write the code that's shown above, the code will throw an assertion the first time its ever called (which will be during unit testing if you're doing 100% coverage). So with your agile method of doing business, that bug might get missed or might not show up when testing the new code but could show up when you run another test.

      And by the way Design By Contract and Test Driven Design work very well hand in hand.

    2. Re:Don't document your code ! by quantum0000 · · Score: 1

      Very, very well put! I would add that you should always prefer labels over comments. See http://www.netfxharmonics.com/document/code/format for details.

    3. Re:Don't document your code ! by geekoid · · Score: 1

      Wrong.

      1) "check that your code behaves as expected." How does that next programmer know what is expected?

      2) "show how to call your code," That's the API documentation, not the code documentation.

      3) Again, how does the next programmer know what the behavior is supposed to be?

      4) "improve the stability of your program, and reduce the QA time." That has nothing to do with documentation.

      yes, write tests. But you need to ALSO let the next program know why you did something and what it's goal is.

      Yes, I have done Agile development, yes I like it, but there is STILL going to be maintenance later on by someone.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
    4. Re:Don't document your code ! by olau · · Score: 1

      Paraphrasing: "Adding tests to your code will require you a lot of maintenance. Every time you change your code, you need to change your tests. It's a never-ending process."

      Not that I necessarily disagree with your point. I just think automated tests have gotten their fair share of hype at this point. They represent a trade-off, just like most other strategies.

    5. Re:Don't document your code ! by eulernet · · Score: 1

      Except that writing tests add value to your project, since you always validate that your code works.

      Documenting code doesn't add any value, except if you write an OS or middleware, and in these cases, you only need to document what every call returns.

      In fact, tests easily replace any kind of documentation.

    6. Re:Don't document your code ! by eulernet · · Score: 1

      1) How does that next programmer know what is expected?

      He has examples on how to call the routine and what it returns.
      I agree that you need to add a little bit information about inputs and outputs, but you can name the variables in a correct way.

      2) "show how to call your code," That's the API documentation, not the code documentation.

      Do you mean that you write 2 documentations ?
      Good luck !
      When you code, your API is your code.

      3) Again, how does the next programmer know what the behavior is supposed to be?

      He has examples of the inputs and their outputs.
      Unless your code is terribly complicated (which means that you probably didn't subdivide it enough), there is no real need to document code.
      I rarely saw code that was impossible to understand, when the number of lines was small (and yes, I wrote large programs in assembly language).

      4) "improve the stability of your program, and reduce the QA time." That has nothing to do with documentation.

      It's a side-benefit.

      but there is STILL going to be maintenance later on by someone.

      You are totally right.
      Now, let's see where you want to spend your time:
      1) maintaining a documentation that will be probably useful in a few years (and in general, the code is so old, it sucks and nobody wants to maintain it)
      2) maintaining tests, that will "document" the routines behaviour, and checks that there is no regression.

  47. make them troubleshoot it by misfit815 · · Score: 3, Interesting

    I work for a firm that conducts a periodic release of code to its production environment. Those of us who regularly work the "release night" know what it means to document code well (and no, it's not just comments in the code). What our firm, and others like us, needs to do is rotate everyone through that situation, or others like it, so that they can see the flipside of their effort. Having to troubleshoot poorly documented code is a good way to instill in a developer good documentation habits.

    --
    Jesus told him, "I am the way, the truth, and the life. No one can come to the Father except through me. - John 14:6 NLT
  48. Programmers != Software engineers by ktrnka · · Score: 2

    If you want documentation and comments, to start with you should stop calling them programmers.

    If you want documentation and comments, you call them software engineers and you allocate time for documentation, commenting, optimization, debugging, and other critical non-functionality tasks. Managers typically only allocate time to develop something that sort of works, not something that's polished, maintainable, debuggable, extensible.

    1. Re:Programmers != Software engineers by ogar572 · · Score: 1

      You are completely right on this. The keyword is time.

  49. It's a matter of time and nothing else by chimerafun · · Score: 2

    I've run several engineering departments. Some have been good at documentation, others not so good. What's the difference? It's quite simple. Time When a company demands quick turnaround, its all the developer can do to get the code out the door. Good documentation falls by the wayside in these instances. In my experience its more about demands from the top than anything else.

    1. Re:It's a matter of time and nothing else by geoffrobinson · · Score: 1

      I think people would understand this if they simply stopped and asked the question of why people don't document to those who don't document.

      --
      Except for ending slavery, the Nazis, communism, & securing American independence, war has never solved anything.
  50. It's not just the comments by jtseng · · Score: 1

    You can read comments in source all day until you turn blue in the face, but you won't truly understand how something works or why it was put together the way it was unless there was some high level document describing major components and how and why they were assembled the way they were.

    Recently I revisited code I had to put on the back burner from early last year. Of course my memory of the details had atrophied and didn't remember how it worked. But because I had written both in-line comments and high-level documentation describing how and why I did what I did, I was able to get up to speed in a minute. Granted someone else who looks at my stuff would take longer to understand it, but IMO it'd take them longer if they had just in-line comments.

    --

    Sanity.html - Error 404 not found

  51. The truth is... by PortHaven · · Score: 1

    That specs often don't match up to real world. Bugs and logic errors exist.

    So more often than not, a developer is doing several re-writes & refactoring of code to achieve a final working version. Documenting each variance would consume so much time that the developer would be fired for poor performance. To a developer, it is more important to retain job, (eat, have a place to sleep, etc) then to continually document during development.

    The problem is in the "check-in". There should in fact be a policy of alloting time for documenting. Once a final or near final portion of code is checked in, shown to work and behave and play with other code, and shown that the specification was indeed correct on the desired functionality needs. THEN the code should be documented for future benefit.

    In fact, if one is using a source code management tool. One can enforce documentation by requiring a second check-in version as File-Documented.

    But time needs to be alloted at the end of a task to document. More often than not, a developer is working on a time constraint. Management wants the fix/update as soon as possible. Developer checks code in as soon as complete so as to resolve the real world issue, and is almost immediately handed a new task.

    So yes, this is a management problem, not a developer problem.

    1. Re:The truth is... by geekoid · · Score: 1

      ". Documenting each variance "
      You comment the why you are doing something. refactoring does not change that.

      And it should take you 30 second to write the why. If it takes you longer then that, then either you don't know what you are suppose to be doing, or your object/function/procedure is doing too much, break it up.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  52. Problem by Anonymous Coward · · Score: 0

    Documentation is always the same problem, everybody wants it, nobody wants to pay for it.

  53. Automatically enforce it by Routrout · · Score: 2

    The best way to have programmers write quality code is to automatically enforce it. Have an automated tool verify the code for comments and run it on your build server each time new code is committed. I am a .NET developper, so each time I commit code, StyleCop and FxCop are run on the build server. This means my code is always commented, hell even spelling errors are not allowed! If I am too lazy to comment, the build server sends an email to the whole team informing them of my laziness.

    1. Re:Automatically enforce it by Dwedit · · Score: 1

      FXCop can introduce bugs into programs. I remember a case where someone was trying to follow the "You must explicitly provide every argument possible" restriction. This is where you get warnings when you call a version of a function that doesn't take in every possible parameter. It leads to guessing games as to what the remaining arguments should be. Sometimes you guess wrong, and the code ends up behaving differently, but FXCop is now happy you've filled in every possible argument. So we go from working code that provides 3 parameters to a function, to possibly-working code that fills in all 8 parameters for the function. Leads to buggy, less-maintainable code.

    2. Re:Automatically enforce it by Routrout · · Score: 1

      I agree FxCop warnings are sometimes intrusive and ignore the context of your application. But you can exclude the rules you do not like from the analysis. I still find FxCop somewhat useful to police and enforce some good coding practices.

  54. Give them a choice by Anonymous Coward · · Score: 0

    Document your code vs. find a new job. Pick one.

    That said, a nightly Doxygen build on commented code goes a long way towards satisfying this. Not is not perfect or complete, but it is a start.

  55. We need to talk about your TPS reports by Joe_Dragon · · Score: 1

    Did you get the memo?

    Ah! Yeah. It's just we're putting new coversheets on all the TPS reports before they go out now. So if you could go ahead and try to remember to do that from now on, that'd be great. All right!

  56. Somewhat simple solution by Anonymous Coward · · Score: 0

    After dealing with a developer who refused to code database closes into his Java routines (or acknowledge the havoc it played on systems), I added "all code (new/changed/extant) must properly deallocate resources when no longer needed for execution" as a prerequisite to all sections of his annual performance review. Miraculously, dead database connections disappeared after the first release that year.

    Management gets what it requires: if you don't demand good documentation, then you don't get it.

  57. Team Leads/Architects, not Mgrs, are the problem by jlusk4 · · Score: 1

    It's not management. It's not lack of financial incentive. Mgmt doesn't have time/energy to scrutinize docs, and paying for docs is stupid because you'll get filler.

    It's thought leaders on the team. You get some architect who wrote the system and fully understands it, PLUS he's smart, PLUS he's a git r done type (remember? remember? smart, gets things done? Thank you, Joel Spolsky). Result: the smart guy everybody looks to writes no docs. He doesn't need them. It doesn't occur to him that others might need docs, because it's not an immediate problem (fire, crisis) he can put out and be a hero. It's friction. No payoff for him to eliminate _that_.

    So, everybody on the team follows his lead. There's no team culture of helping each other out by writing little love notes to each other that say such sweet things as "Returns the two highest priority items that are neither red nor flibbertygibbits (<see cref="isFlibbertyGibbit()"/>)."

  58. I document for myself by tuffy · · Score: 3, Insightful

    Six months from now, long after I've moved on to something completely different, am I going to remember a function's return values? The inner workings of a particularly complex algorithm? Or the reasoning while a special case has to be handled differently?

    If it's not going to be obvious to myself later on, it's worth adding a concise comment to explain.

    --

    Ita erat quando hic adveni.

  59. What is the goal by EmperorOfCanada · · Score: 2

    First, what is the goal? The goal is not well documented code, what use to anyone is well documented code by itself. What you are looking for is a product that works and is easily maintained. Good code and any documentation is a huge part of easy to maintain. But where many people go wrong is that they see code documentation and commenting a critical part of a project. To the point where it starts to interfere with the creation of a good product that is easy to maintain.

    So when looking at documentation it needs to make sense for the endgame. Who is going to use it? When are they going to use it? How much effort is going into its creation? I have seen projects where thousands of pages of documentation were generated where the only thing ever read again(other than by the document review team) were the few pages that documented the steps for configuring the server. When the next version was created nobody referred once to the old pile of documents that had every detail in the universe.

    The next question is: what is documentation? This might seem odd but documentation can be the very directory structure itself. I wonder where the client code, maybe it is in the directory named client_code.

    In agile or XP programing you don't tend to look too far into the future. So two critical documents that would be very active are your todo list for this cycle and a wishlist for future cycles that eventually turns into a todo list. The todo list, when done, can be chopped up into a crude set of documents that show the past if anyone were to be interested.

    Lastly the code itself is an excellent place for documentation. A quick explanation of what it is about and why it exists can be useful if the file isn't already named verifycreditcardnumber.c.

    So I don't think the criteria is so much poor or good documentation; so much as it is about useful documentation. If non programmers are intimately involved then lots of screen shots, text, and flowcharts are needed. If programmers are the only parties then it might almost all hide in the codebase with the exception of the screenshots mockups.

  60. I never understood this... by roc97007 · · Score: 3, Insightful

    I always document my code. It saves time later. Six months down the road I'm not asking myself "why the hell did I do that?" It's for my own protection. I've had programmers tell me that they don't document their code because it's obvious what the code does, and sometimes that's true. But I think at least some of the resistance later to add features or fix bugs has to do with not wanting to struggle to remember what the code does. And -- this is just me, but -- you probably don't want to have a reputation for being uncooperative and not a team player in a down economy.

    In a very early job, a guy with more credentials than I wrote a program we all used in a language I didn't know. There was a longstanding bug which he refused to fix [1], and he kept the source in a protected directory. So one night we broke into his account, I scooped the completely undocumented code, figured out the problem (had to change *one* (1) character!) and distributed the new binary. It took him awhile to figure out what happened. Boy was he pissed.

    [1] Whether this was a dominance game or he really did not want to try to figure out the code he had written months earlier was a point lost in history.

    --
    Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
    1. Re:I never understood this... by AnalogDiehard · · Score: 1

      I work at a company where we are protective of our IP yet knowledge sharing in internal channels is encouraged and you are actually rewarded for the effort.

      I have always commented my code. In my line of work I am often asked to come back to debug a system six months since I last touched the code. The comments are there to clear the cobwebs that develop in my brain after six months. They are also there for knowledge sharing, especially when someone else can resolve a problem when I am out of the office and can enjoy a vacation without interruptions.

      I have seen "engineers" who refuse to document their code in the interest of job security. They only make their own lives harder and more than once I have seen cases where they are let go and not asked to come back. I have also seen companies with a turnover history due to replacing experienced workers with cheaper labor and this kind of culture will frighten engineers into a protective mode, and they won't comment their code for fear of getting replaced.

      --
      Eternity: will that be smoking, or non-smoking? I Corinthians 6:9-10
    2. Re:I never understood this... by roc97007 · · Score: 3, Interesting

      > I have also seen companies with a turnover history due to replacing experienced workers with cheaper labor and this kind of culture will frighten engineers into a protective mode, and they won't comment their code for fear of getting replaced.

      I'm living that dream right now; we've replaced a couple hundred experienced, in some cases brilliant IT people with convenience store shelf replenishers with only a few weeks training. So it does happen. And yes, it has been an unmitigated disaster.

      The problem is, the people who make the decision are not the people equipped to understand the ramifications of uncommented code. Even when it's pointed out to them that they're going to lose a gigantic amount of crucial tribal knowledge, they'll go ahead, with dollar signs dancing in their eyes, and pull the ripcord anyway. And then what comes out of the bag is a bunch of camping gear instead of a parachute. (Sorry, I just flashed back to an old Road Runner cartoon.)

      The point is, not documenting your code is not a good strategy for job retention, for the reason you state (when this behavior is spotted they're more likely to be replaced with someone who's better at documentation) and also for the reason that upper management isn't even aware that code has comments, or that it's not a "procedure", it's the culmination of a lot of knowledge and experience, which isn't easily replaced by a written set of instructions. I would also add that a crew who is secretive, doesn't work well together, and takes forever to fix stuff due to having to reverse-engineer their code, is more likely to be outsourced than people who are doing their jobs properly. I hasten to add, crap happens even to good teams (it did here) but it makes it easier to argue against the decision if you're defending a stellar team.

      --
      Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
    3. Re:I never understood this... by Anonymous Coward · · Score: 0

      Awesome story, thanks for sharing it.

    4. Re:I never understood this... by Anonymous Coward · · Score: 0

      When you fix a bug, that's an excellent time to fix any out of date comments, or add new comments, especially if it is a head-scratching tricky bug. You have to look at the code in detail and read the existing comments and understand what is going on anyway. Maybe you spend an hour or two hours locating and fixing a tricky bug, so can spend ten or twenty minutes fixing the comments without impacting too much on the time it took to fix it. If while fixing the bug you had to stop and think for a few minutes before you figured out what a section of the code was doing, then the chances are that it could do with a few comments to help future programmers (including yourself) so again it's worth spending a few seconds writing in those comments yourself.

      In some ways the debugging phase is often a better time for commenting than the coding phase as you are just that one step removed from the original coding. There I include as well as the post release or post beta debugging, also the syntax error fixing and immediate minor bug fixing phases as well, all excellent times to improve the comments, if you needed to spend any time at all figuring out what the code does then it needs comments.

      Another thing, while debugging, as well as noting the bug fix in the developer's change log for the code, if it is at all tricky, then I put a comment about the bug fix in the code itself. This helps prevent anyone in the future accidentally reintroducing the bug in a future edit of the code, or introducing similar bugs. You can also just comment any bug fix as it happens and keep those comments for at least a short time after the bug fix as a way to cross link the change log with the code, I've taken to doing that a lot recently in my own code (with the idea that later those minor comments can be removed) but interested to hear how others deal with commenting bug fixes.

      Do any of you comment bug fixes as you do them in the code itself (rather than separate documentation such as developer's change log), and what procedures do you use if you do?

    5. Re:I never understood this... by roc97007 · · Score: 1

      > Do any of you comment bug fixes as you do them in the code itself (rather than separate documentation such as developer's change log), and what procedures do you use if you do?

      Whenever I do a potential bug fix, I always add a comment describing briefly what it's supposed to fix, my initials, the current date, and the string TEST TEST TEST. That way I can easily find and revert the change if it didn't fix the problem. After testing, if everything is ok, I do one more pass through the code and remove all the TEST strings, leaving the description, my initials, and the date.

      Going back through the code later is a lot like reading through your older postings in Facebook. Sometimes illuminating, sometimes entertaining, sometimes embarrassing.

      --
      Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
  61. Pick two by Nanosphere · · Score: 1

    Good / Fast / Well Documented

  62. Real World by geoffrobinson · · Score: 2

    I will document when I'm given the time to document.

    If it's always the tyranny of the urgent, if there's always some fire to put out, I won't have the time to document.

    I had a job where the manager was always complaining we didn't document. But he never fought upper management to give us time to document.

    If you say "I have to have documentation and it is a deliverable" you will get it. If there is always something more important to do, it won't get done.

    --
    Except for ending slavery, the Nazis, communism, & securing American independence, war has never solved anything.
  63. The Code Isn't the Problem by Greyfox · · Score: 2
    Code doesn't happen in a void. It's there to support the business. If you understand your company's products, business logic and the customers they sell to, you can write good code to support those processes. It is the business which you must explain to new arrivals on the team. It is the business logic which must be clear to anyone supporting the code.

    The agile people say you must never comment at all because you might change the code and then your comments will be wrong. This is only true if you're describing what the code is doing. If you are describing how the code supports the business, the comments will probably still be correct.

    The scholarly types say you must comment profusely. Certainly comments help in areas where the code might be confusing for a newcomer, but no amount of describing what the code is doing in any given piece of code will shed much insight onto the business processes that code supports. Many programmers out there are just... bad... and they will probably not read the comments and screw up your code, anyway. Not that this is a reason not to comment your code. Having a comment with a warning might constitute useful proof of a given programmer's... badness... in the event that your code is screwed up in the future. If you comment, it is wise to make sure the evidence is something you wouldn't mind having come to light in the future.

    Code itself is a specialized language by which two programmers can communicate, often across a gap of many years. An understanding of the business is both required and usually assumed by one programmer or another. If one of the two programmers has a less-than-perfect understanding of the business, his code will reflect his confusion. If the programmer reading the code has a less-than-perfect understanding of the business, he will find the code confusing no matter how good the comments are. If both programmers have a less-than-perfect understanding of the business... well... that's the situation we most often find ourselves in. And that's usually when people start complaining about documentation.

    --

    I'm trying to teach myself to set people on fire with my mind... Is it hot in here?

  64. I agree, 110%... apk by Anonymous Coward · · Score: 0

    Others who wrote they're doing it to protect themselves are MY kind of guys, because it's exactly what you're doing & for the right reasons (if not for protecting others who MIGHT work on your wares later).

    APK

    P.S.=> It's NOT like you have to "comment every line" but more on the 'engines/algorithms' you built so you can understand them months-to-years down the road without a lot of "catchup time" in step-tracing to try to "re-understand" what it was you were doing "back then"!

    (This works to help others too, who may get stuck maintaining your work (usually a rarity unless you left for greener pastures though, imo & experience - YOU usually have to "patch" or update your own work, which makes a lot of sense & saves time usually because the "oem" of the code is you, after all))...

    ... apk

  65. Good documentation and good writing are hard by gestalt_n_pepper · · Score: 1

    Very hard. For some people. The code tells you what is being done. Sometimes that requires a line of explanation. The rest of the cognitive layer (i.e. the code documentation) tells you why something is being done a particular way, so you don't have to engage in another expensive research project.

    The best exercise I ever had in documenting code was rewriting a colleague's code. All I did was take the comments, sentence by sentence and rewrite them using the least number of words that preserved the concept. Paragraph length sentences often reduced to as few as 10 words. That's not all, of course. Some comments were eliminated; others were rewritten in their entirety. All were arranged to emphasize the flow of concepts, rather than the specifics of the code. It's nontrivial.

    --
    Please do not read this sig. Thank you.
  66. You make it a thing everyone does by Sycraft-fu · · Score: 2

    It really can be done. If your company has a culture where it is just how things are done, people will do it because it'll be more bother for them not to (as they'll get bothered when they don't).

    I'm not saying it is trivial to do, just that it can be done. You have a corporate culture where that is how it is done, and people on all levels understand it, it'll be done. When the John Wayne programmer who refuses to do it comes in, he'll learn when every time he submits code it gets kicked back and the team lead comes and explains again that you have to follow certain conventions, document, and so on.

    As an example of where it does happen would be Microsoft. If you talk to anyone who's seen the Windows source (either at one of the many universities that has a license to have it, or from the leak a few years back) they'll tell you it is very good in that regard. It follows consistent conventions, is well documented, and so on. That isn't coincidence, it is because they have a culture that demands that.

    I expect it is also the sort of thing you seem more of the bigger and longer term the item is you are talking about. Something like an entire OS like Windows (where you are talking a ton of functionality, not just a kernel) is going to require a good setup since the code will be around for a long time and worked on by many people, and is exceedingly large and complex. When you are talking little "fix it" programs as many people have to do to make something work as a sysadmin, then it is less likely to happen.

  67. Crappy Programmers by Anonymous Coward · · Score: 0

    I worked with a guy who refused to write documentation and when he did he left out the important things. I actually had him say to me "Can't you read the code?" I tried to explain to him that I never see his code and needed to know what the interface to his dlls meant. After that six more months and he was no longer with the company.

  68. Waterfall by Anonymous Coward · · Score: 0

    Documenting code is the waterfall method, i.e. you are swamped if something changes and every line of your code is "in pictures". Instead document the design sketches to the most appropriate level so that everyone understands the meaning, also put enough comments to the source code itself.

    Waterfall and Agile are both good but the former needs the designer-programmer division and strict management with less creativity and thinking. The latter needs more thinking, more scientific and abstract thinkers in the execution phase (best if designer is also the programmer).

  69. Start with the requirements analysis. by meburke · · Score: 1

    One requirement should be that code documentation, clear enough for a junior programmer or someone from the accounting department to successfully follow from start to conclusion, shall be produced for each component along with the code.

    Then, the project leader shall be responsible for seeing that code, and its documentation, is included in the check-off document for each system, subsystem. and function.

    Publicly "score" your programmers for the elegance and completeness of each milestone task. If I was the project manager I would probably run each component through Rose or some other UML environment to be included in the documentation (after it is compared with the original/changed design).

    Changes should also be documented. So should maintenance changes, but that is usually where I find the least comprehensive documentation. It is the leader/manager's responsibility to make sure the PROJECT is complete, not just workable. It is the developer's responsibility to make sure that his/her portion of the project is complete, not just workable. If the developer can't write a description of what he did that could be understood by a dumb-ass, then he probably doesn't know what he's doing anyway.

    --
    "The mind works quicker than you think!"
  70. Don't by iamacat · · Score: 1

    If the code can not be understood by reading, the consequences of even isolated out of date or mistaken comments are disastrous. Imagine a function that claims to authenticate users but doesn't. Instead, consider using higher level level languages and tools as well as separate utility methods - like heap sort - from business methods. Documentation if for design and protocols, not for what each line of C does.

  71. Document the "Why" not the "what" by 140Mandak262Jamuna · · Score: 2
    Ridiculous, useless, redundant comments reduce the signal to noise ratio. I would term "This function calculates the area of a triangle" or "this function changes the state of widget" to this category. Just pick some very sensible function/class names and be done with it.

    What must be documented are the complex procedures and why it is doing it. Or if a previous simpler approach has been tried and then removed for a different non obvious procedure, that fact must be documented. Example:

    "This class maintains a multi map of triangle pointers, sorted by area, to solid body faces. The sort key is a double, the truncation errors differ between Linux and Windows, so the order of visitation is not the same. When we used a simple std::multimap(Triangle *, FaceList, double),[*], the tables had different orders in different platforms. To provide repeatability we use a tolerance and tie breakers to make sure in both platforms the table will have the same order. It is called by render class, in a not very deeply nested loop. So CPU performance is NOT critical. Code is written for ease of maintenance and development, not optimized for CPU or memory." Such comments are useful, if maintained and kept up to date.

    But most of the time it is not done. You see beautifully formatted comments created by macros in the editor, that occupies so much of screen real estate, I am not able to see both the code and the comment. Example:

    [*] Syntax nazis: Slashdot formatter would not let me use angle brackets there. So I used () for illustration. /***Function Foo**/

    /**Author Iman I Diot**/

    /**Date 1993 Aug 21**/

    /**Returns bool**/

    /**Input int**/

    it so stupid, I feel like screaming. If that coder is still working for me, I can scream at him or her. But mostly it is people who have left the company ages ago dumping that legacy POS on my lap.

    --
    sed -e 's/Chuck Norris/Rajnikant/g' joke > fact
    1. Re:Document the "Why" not the "what" by geekoid · · Score: 1

      You examples are stupid. Sorry, but that are.

      ""This class maintains a multi map of triangle pointers,"
      Why is it doing that?

      Get a good editor that collapses comments.

      " I can scream at him or her. "
      If you ever scream at me, I will trash your car.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
    2. Re:Document the "Why" not the "what" by 140Mandak262Jamuna · · Score: 1

      I will never scream at you. Most likely I would not hire you, and you would not accept if I did. My division is not big enough for both our egos.

      --
      sed -e 's/Chuck Norris/Rajnikant/g' joke > fact
  72. I don't think programmers should document by Bananana · · Score: 1

    ... instead, they should program according to the documentations.

    1. Re:I don't think programmers should document by geekoid · · Score: 1

      Sigh. Yes and No.

      developer commenting is about the why of specific items.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  73. time by Tom · · Score: 1

    Here's what doesn't work: Anything, no matter what, if at the same time you put them under deadlines and other pressure to deliver results by (insert arbitrary, always too-short deadline set by you, your boss or anyone else but the coders themselves).

    When the pressure is building, time is running out and the project is late, everyone in the process considers documentation to be the first thing that nobody would miss. So it's the first thing that gets dumped. And, of course, it's not as if the coders would be given time after the deadline to fix it, because there are no bug reports from clients regarding missing comments in code, obviously, and the next deadline for the next project is already approaching.

    It's one of the many reasons programming as a craft is still in its diapers: Bad management.

    --
    Assorted stuff I do sometimes: Lemuria.org
    1. Re:time by geekoid · · Score: 1

      No. It's an excuse people use to not do it. Code documentation is essential, and if you aren't taking the time to do it into account with your estimates then you need to gain some more professionalism.
      It's not hard, and it doesn't take that long to do.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
    2. Re:time by petes_PoV · · Score: 1

      It's true - programmers hate doing anything other than writing code. They hate meetings, they hate documentation, they hate testing and they hate support work. Coding is fun, it's play, it's making stuff - all the rest is work, and they (sorry: we) don't "do" work.

      However, everyone else is complicit in the failing. In interviews candidates may be given short assignments: write a piece of code to do <X> but they never get failed if there are no comments inthe code -and they are never asked to comment it: just to write the code. So long as it compiles and appears to give a correct result for a narrow range of test data (usually 1 sample) that's all. Job done, interview passed.

      A better way is to package up the tasks at the management level. You don't get to start on the next module until the last one is finished. Finished means the boss has signed it off - and that means it's properly documented. The problem here is that it requires a technically competent boss. One who won't sign off on "increment X" as a valid comment. This also means that the blame for faiilure to deliver sits where it deserves to. If the number of modules per month for a given softie falls below adequacy: say goodbye. The code they produced may be brilliant, but most places want "finished" or "working" above brilliant, any day.

      --
      politicians are like babies' nappies: they should both be changed regularly and for the same reasons
  74. Documenting the "whys" of code by Windwraith · · Score: 2

    I often hear that the proper approach is to document WHY you did something.
    I am not a coding guru or even have formal studies on that field, I am really just a hobbyist, so anyone here has a few good valid examples of a "why"? I'd like to comment stuff properly.
    So far I use non-shortened descriptive names for variables, functions and types, but I don't use that many comments. For example when parsing tokens in a string I write stuff like "//The format is ", but even so I feel the code is doing a better job at explaining it than I do.
    As I went with the lengthy names, I have less problems getting lost on my own code, but I feel I am misbehaving. I blame my lack of formal education in coding, but would like to have some quality standards nevertheless.

    1. Re:Documenting the "whys" of code by Windwraith · · Score: 1

      ...way to go, Slashdot, making my comment example being cut abruptly. Anyway, it was meant to specify the format in order, element by element, and that stuff.

    2. Re:Documenting the "whys" of code by geekoid · · Score: 1

      // Calculate travel time for ship to get from point A to point B.

      That's a why. When I read that, I can know what it is actually supposed to do.

      I use that example, because I was working on that code, and saw that they where taking holidays into account. Hint, ships don't strop in the middle of the ocean because it's Christmas.

      Without the why, I can't know what the goal of the code is, and I can't tell if it works properly.

      Commenting make it easier for different developers to knwo whats suppose to happen,. and in 6 months YOU will be a different programmer.

      --
      The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
    3. Re:Documenting the "whys" of code by Windwraith · · Score: 2

      Well, the way I name functions, it's usually "ship_calculate_arrival_time" (in a "component,action" fashion, so they sort alphabetically as well), but point taken.

  75. Misconception about in-code documentation? by bAdministrator · · Score: 1

    The purpose of in-code documentation is to bring awareness to the various situations surrounding certain parts of a program. Contracts, parameters, and protocols already have a place in documentation of its own.

            You simply need to realize that the human mind goes through a lot context changes when doing programming--it's not likely that anyone has the same mindset the next time they touch the same logic.

            Documentation in this sense is to write as much or as little required to bring awareness to assumptions, consequences, etc--it's not like writing the philosophy of the API, defining its parameters and protocols. You may have already written that, as it's the reference for both your own code, and for the users of the API, and other programmers.

  76. No. it's not do you the process by geekoid · · Score: 1

    It's called being lazy and short sighted.

    If you aren't documenting your code, you are bad at your job.

    --
    The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  77. Measuring readability by John+Bayko · · Score: 3, Informative

    I think the real problem is trying to measure code readability. Policies and coding standards try to address the issue while avoiding it by mandating frills that they think will kind or "imply" readability - function length, number of spaces in parentheses, badly defined Hungarian notation (dead, thankfully), Javadoc or similar commenting standards, and so on. But there's no getting around the fact that the only way to measure code readability is to read it.

    This means that you need to put code review at the centre of the process. Not necessarily anything heavyweight, but just require that one other developer reads and understands the code (and points out any obvious flaws) before committing - with the limit that any questions the reviewer has should only be answered by changes in the code, because a question implies a readability problem. The developer can add comments, or rename variables, or restructure the code to make it clearer, but the end result should be readable code with fewer bugs (bugs live in hard-to-understand code, simply adding some intermediate variables to a complex formula can make them go away).

    As long as the code review itself doesn't get bogged down with issues of How The World Should Indent and things like that - that's always a risk with developers looking at each others code.

    1. Re:Measuring readability by rufty_tufty · · Score: 2

      As long as the code review itself doesn't get bogged down with issues of How The World Should Indent and things like that - that's always a risk with developers looking at each others code.

      That's why my favourite style to do code reviews was "Justify your warnings" from the various tools that read the code.
      Most people agree that some warnings are just the compiler being over-zealous, and those parts of the review went fast; but those around bits of code that others didn't understand took a lot longer (this also encouraged you to get rid of the easy warnings and sloppy code before review just out of laziness), those warnings that scared people but you were sure was just because you had no other choice again gave valuable feedback.
      It worked well for us anyway...

      --
      "The weirdest thing about a mind, is that every answer that you find, is the basis of a brand new cliche" -
    2. Re:Measuring readability by mandelbr0t · · Score: 1

      The developer can add comments, or rename variables, or restructure the code to make it clearer, but the end result should be readable code with fewer bugs (bugs live in hard-to-understand code, simply adding some intermediate variables to a complex formula can make them go away)

      "Don't get suckered by the comments -- they can be terribly misleading. Debug only code." -- Dave Storer

      This is why I always add my documentation at the end. A good programmer knows how to use his debugger. Properly named variables and methods will allow you to step through a program until you understand how it works. Once your understanding is clear, and you are quite certain that the code is good enough for somebody else, add enough documentation to aid other programmers in using or maintaining your code. The only way to know how much is needed is through the code review. The only exception I can think of to this process is when releasing the source code to the general public or to a client for their own maintenance. Since you don't usually have a code review with them, it's best to go for overkill. A pain sometimes, but a necessary part of a complete product.

      --
      "Please describe the scientific nature of the 'whammy'" - Agent Scully
    3. Re:Measuring readability by omglolbah · · Score: 1

      I've recently had to look at some code which handles the process control of a 'slug' catcher in an onshore oil/gas pipeline facility.

      The code has 7 different constants defined for everything from density of MEG (antifreeze) to temperature variables...

      Sadly none of them have comments... And the language in question does not support variable names (Heh... wish I was kidding). Everything is named by 'block number'. So block number 1234 will have a value of 3.19387 and no comment about what it actually is or does.

      The code is efficient and useful as hell, but with only an overview of what the whole function DOES but very little about HOW it does it makes it mostly useless for future changes. In the end it might get junked and re-implemented but for now we've just copy-pasted and simulated hoping it will behave... Time and money constraints :(

      There are all kinds of environments and usage cases and I wish there was an easy answer to any of it *sigh*

  78. COBOL baby, COBOL ... by serbianheretic · · Score: 1

    Use COBOL. Those guys in 1950's sure knew their stuff. Self-documenting code. It forces you to write almost normal English.

  79. Re:Documentation is usually worthless by geekoid · · Score: 1

    If a function get so out of date that it original intent is no longer valid, you fail as a programmer.

    "explain what a piece of non-trivial, non-intuitive piece of code does."
    so you know what every other programmer in the world find intuitive?

    You also assume you did it correctly. Something everyone else will need top assume if they don't know the point of the function up front.

    I have seen this all too often. Where the code looks like its doing everything write, but it turns out is doesn't and it takes hours toy figure that out because the dip shit didn't bother to tell anyone the point of the procedure.

    When ever I find this, I ALWAYS tell managers that I would have been done quicker if the original programmer had been professional enough to leave a 30 second comment.

    Yes, unit test are critical. They shorten QA*, and make it easier to find gross bugs.

    But you can write code that passes a unit test but is still flawed.

    *really part of QA

    --
    The Kruger Dunning explains most post on /. http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect
  80. Comments are technical debt by Anonymous Coward · · Score: 0

    Comments aren't automatically checked and often can't be trusted to be correct in the future. Forget comments, write code that rarely needs them.

    Get your developers to use Programming by Intention or Compose Method. Write Cohesive methods and classes and comments will be less important.

    Save the comments for describing unique algorithms/issues and let the code describe the rest.

  81. Mitt Romney says don't document code by Anonymous Coward · · Score: 1

    He likes to fire programmers!

  82. Code changes faster than you can comment by Anonymous Coward · · Score: 0

    You do iteration X, and get feedback to make changes for iteration X+1, and then here comes iteration X+2. Who has time to go back and comment all this stuff? Nothing is funnier than JavaDoc comments in books - yeah, like I have time to comment my code in that fancy format and document every class and method and generate HTML doc and so on.

    Of course, Android has all that fancy doc. And it's a steaming pile of beta, where there's documented Android and the real hacks you have to do to get anything to work. WebSphere is well-documented to, and it's incomprehensible.

    What was the InfoWhatever shill's point again?

  83. Motivation: poor memory by Tablizer · · Score: 1

    I document my own code primarily because I have a crappy memory. Perhaps if you kick the problem programmers in the head enough, they too will have crappy memories and want to document their stuff.

  84. Lack of documentation is a sign of poor management by Anonymous Coward · · Score: 0

    It's ridiculous to blame programmers for lack of documentation. Lack of documentation, like any other problem with a team, is a sign of bad management or bad process. It's generally a problem with unrealistic deadlines.

    Sure, if all the developers on your team are great at documentation except one guy, then you can blame the developer. But if most of your developers aren't properly documenting their work, then the problem is the management, not the developers.

  85. Comments in conf, bare minimum by hamsjael · · Score: 1

    Comments and documentation about the code is probably necessary, but where i work as a sysadmin/customer consultant. my main problem is that not even the runtime configuration options are documented by our cowboy developers (microsoft style, you know with an ini file without a single comment). Off course the devs whine everytime they have to do support because nobody but themselves have a chance in hell to understand whats going on, but them selves! i am contemplating putting a wall between their dev systems and ANY demo system. so that only a sys admin can install their code for demos ? (forcing them to make the application deployable by someone who havent acually written the f****** code.)

  86. Re:Linux kernel source by Anonymous Coward · · Score: 0

    Linux kernel source, including driver source, seems to be produced with the attitude "If you can't puzzle out this self-documenting C code then to hell with you." Did you know that on a random PPC the Linux kernel text is not marked read-only the way it is on a 386? (BAT entries are used instead of page tables for the kernel.) That was fun to discover, wasn't written down in the source. On the port to your particular board, do the dma_sync and pci_sync calls do anything or are they no ops? Very difficult to tell, definitely not written down.

    In a code review we asked an author to stick in more comments. "Why? I'm adhering to the Linux standard." "Yeah, but we still can't figure out what what the hell you are doing."

  87. Yes Pay us Gobs of Money by StillNeedMoreCoffee · · Score: 1

    I'll even document somebody elses code,,, just kidding. Bazinga

  88. Future article in Slashot... by sapgau · · Score: 1

    "How to make sure developers maintain comments to reflect changes in code"

  89. Shortsighted by pickin_grinnin · · Score: 1

    I always document my code. It's really not that hard to do, particularly if you do some of it while you are still coding. Back in the mid-90s I worked for a company that forbade it's developers from documenting code. You could actually get in trouble if you did it. Their thinking was tha it was a "waste of time" and didn't add anything of value. I strongly disagreed, of course, but they wouldn't budge. It was very frustrating.

  90. I forget where by ThatsNotPudding · · Score: 1

    but in a list of programming truisms, was:

    "No documentation! If it was hard to write, it should be hard to read."

  91. Good Enough by tomhath · · Score: 2
    FTA:

    useful rule of thumb is that programmers should produce documentation that's "good enough" -- and no more. If it gets the job done, it's probably good enough. Any additions are just as likely to be redundant. If that sounds vague, that's because it is;

    Thanks Mr. McAllister, that clears it up completely. Bribe, threaten, or otherwise coerce programmers to do ... something, but I don't know what that something is.

    I worked on a very large project a few years ago where the company did a study to correlate the number of comments with the number of reported bugs in the code. It revealed exactly what I already knew: the more comments in the code, the more bugs were reported against it. There are several reasons for that (complexity of code, skill of programmer, etc). Fact was that while fixing all those bugs we found that the comments around the bad code were usually incorrect: the code didn't do what the documentation said it did. So out of necessity we adapted to the situation, first thing to do when fixing broken code was remove the comments (because you shouldn't trust them), then figure out what the code really did, fix it to do what it was supposed to do, and (possibly) add back a few succinct comments that were correct.

  92. Simple steps by Todd+Knarr · · Score: 1

    You want developers to document code? OK, a few simple steps:

    • Allocate time for documentation. Don't make it an extra step, make it an explicit task in the schedule with time assigned to it just like analysis, coding or testing.
    • Don't skimp on that allocated time. Don't expect the developer to be doing debugging or anything else during that time. Don't shave time off documentation to make up for delays elsewhere. You wanted documentation, let the developers work on it.
    • Give the developers help. Half of documentation is writing down the details. The other half is formatting and editing what they've written down into something clear, comprehensible and consistent from one set to the next. Developers know Visual Studio, they aren't experts on Word. They have templates for code, they don't have templates for Word documents. Find a couple of people who are experts on Word and assign them to work with the developers to help turn raw words into nicely-formatted real documents. Make it clear to both sides that, while they're not expected to become an expert in the other's area, they are expected to learn enough about it to help make things work.
    • Don't skimp on the developers and the formatters/editors learning what they need to learn. If the developer needs to take a couple days to work through that tutorial on Word templates and how to use them, don't gripe at them and keep asking them to work on other stuff instead of the tutorial. Ditto if the Word people need to actually do a basic programming tutorial. You wanted this done, let them learn what they need to learn.
    • Organize the documentation once it exists. Before you start, plan on creating a Web site or something to hold the documentation. Make it something that developers can actually search with a reasonable expectation of finding what they're looking for. A big folder full of files won't be any use, the only people who'll be able to find what they need are the ones who already know it. It should have a table-of-contents listing organized by module and component (so someone who only knows they want documentation on component X will immediately see the heading for it which'll bring up all the documents with descriptions of what they're about) and a searchable index (so people can enter keywords and get back a list of all documentation that talks about those keywords). Same thing for a nice documentation library that requires software that the developers don't have on their machines, or that presents things in a form they can't copy from or that won't adjust to let them see all the documentation and have Visual Studio running full-sized at the same time. Developers won't feel documentation's useful if they can't use it in their normal environment, and they won't feel motivated to produce it if they don't think it'll be useful.
  93. a way to improve the explaining experience by Walt+Dismal · · Score: 1

    Documentation might be improved if it were made more of a social activity instead of a chore. That is, if the process is made one of interaction with other people, providing feedback and direct contact. For example, an informal whiteboard discussion followed by a writeup and then formalization. Few people enjoy laborious banging away on a keyboard explaining, but probably people will find it a lot easier to give a general explanation followed then by the detailed structured written material. With social interaction, it can make it easier to see when what is clear to you is not clear to others, hence needing better coverage.

  94. Real programmers don't document by Tony+Isaac · · Score: 1

    If it was hard to write, it should be hard to understand!

    http://www.thinkgeek.com/homeoffice/stickers/9d48/

  95. Trolltalk.com/tomhudson/gmhowell/squiggleslash by Anonymous Coward · · Score: 0

    Failing as usual, & this time, by their sockpuppet account, MikeK!

    Yes, I own the place, & bought it from a relative (paid in full & taxes up to date) and had a relative living w/ me years ago too who moved out around 3-4 yrs. ago.

    (So, I live there too, makes sense: I own & maintain it (and I own rental properties as well) - How about you?)

    * I've asked that of you before during your off-topic illogical failing attempts @ ad hominem attacks upon myself - "funny" (not) that you NEVER answer that question... it only ends up making me look good as usual, so thanks for that (decent tax paying kind of guy here!).

    APK

    P.S.=> What are you, somekind of "online stalker psycho anonymous troll", or what? LMAO, man - grow up!

    Face it - you WISH you were me!

    Quit stalking me with your "trolltalk.com" pals I busted in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    They've got issues (you're just another of their registered account sockpuppets). For years now they've done that, in gmhowell, tomhudson, damn_registrars, webmistressrachel, squiggleslash, sardaukar, countertrolling, & other guises as well... apk

    1. Re:Trolltalk.com/tomhudson/gmhowell/squiggleslash by MichaelKristopeit490 · · Score: 0
      ur mum's face're just another account sockpuppet.

      i am michael kristopeit. i've stated this quite clearly. i live at 4513 brittany ct. eau claire, wi 54701... i live there in the home i paid cash for. i live with my wife and 2 children and 2 dogs and numerous firearms.... i've told you a ll of this many times... yet you continue to ask if i own property? you're an idiot.

      i have absolutely nothing to do with gmhowell, tomhudson, damn_registrars, webmistressrachel, squiggleslash, sardaukar, countertrolling. you can comprehend that multiple individuals would have the same reaction to your ignorance, mainly because of that very ignorance.

      why didn't you mention your best friend jay little?... he said that the woma n who was pictured with you asked to be cut out of the picture because you abused her. do you think that a man that ab uses a woman should grow up? i do. how about you?

      you're an ignorant hypocrite.

      cower in my shadow some more, feeb.

      you're completely pathetic.

    2. Re:Trolltalk.com/tomhudson/gmhowell/squiggleslash by MichaelKristopeit490 · · Score: 0
      i suppose owning a rental contract to live with your mother in the basement could be construed as "owning rental property"... you do own the lease after all....

      apartment #1... lower level... of the shanty.

      looks like you have lots of satisfied customers

      cower in my shadow some more, feeb.

      you're completely pathetic.

  96. Automation by Martin+Spamer · · Score: 1

    There are tools that will reverse engineer code to produce UML, or DB schema to produce ER diagrams. Add good naming conventions, IDE automatic code completion in IDEs combined with tools like JavaDoc go a long way. These need to be ubiquitous.

    The same process improvement we've seen automating the build, unit testing and deployment needs to be applied to take the donkey work out of the documentation process.

  97. Get comments first by Shotgun · · Score: 1

    Ask to see their comments before they start on their code.
    I find that if I will write out what I want to do, prepend a comment character to the start of each line, and then start coding, that I stay focused and proceed much faster.

    --
    Aah, change is good. -- Rafiki
    Yeah, but it ain't easy. -- Simba
  98. Professional Standards by HarryatRock · · Score: 1

    A professional follows standards appropriate to the job in hand.
    Coding is but one step in the process of creating software, and not more or less important than the others.
    Any job needs a design stage, the output of which is documentation.
    Some jobs need very detailed design stages, possibly including pseudo code.
    Every job needs an implementation stage, this should include documentation as to why a particular method or structure is used.
    Every job needs a testing stage. Even the smallest job should specify a minimal test data set. Mission (or life) critical systems should specify a test environment which covers the whole envelope of parameters / states which the software is expected to handle ( that is not the same as expected to meet).
    Every job needs a sign-off stage. Self certification should only be used for very simple jobs, and even then should include a statement by the designer/programmer/tester(s) that the stages have been done, or why in this case they have been skipped or are continuing at the same time s release. Yes it does happen even in the best shops, but for Turin's sake write it down, and insist on it being done before further change to the affected software.
    In a really good shop, with a proper development environment which includes source code locking and version management, stage completion certificates should form part of the build dependency tree.
    If you are a manager of a shop which does not have such standards, then it is your professional duty to implement a scheme which allows you to certify that software that you release is fit for purpose. If you have staff who will not or cannot work to such standards, then I suggest that you ask them to sign a release form in which they accept personal responsibility for any failure. If they are willing to sign that, then you should be able to persuade them that proper design documentation is a good way to cover their asses.
    If you are a "coder" in a shop without proper standards, then are you a professional? If you are you will set up your own scheme and stick to it.
    Carrots, sticks, medals and back patting may have their place in life, but if you want to be in a profession, then standards are an inevitable component of the job. That's what profession means.

    Encourage your staff and your peers to follow standards, and get involved with developing local procedures which help you to produce software fit for purpose (and that is not just fit for release).
    Now get off ,my lawn, I have to finish documenting a load of COBOL before I can get out of purgatory.

    --
    nec sorte nec fato
  99. Jay Little claimed to be an Exchange expert by Anonymous Coward · · Score: 0

    Yet he didn't know memory optimizer programs unhalt frozen exchange servers. I proved that to him and 1,000's of others reading, & with Microsoft's own documentation no less!

    He ran from the Windows IT Pro forums in shame because of it...

    ( & he then tried to go off topic and on ramdisks/ramdrives and failed again on yet another forum vs. myself publicly, @ NTCompatible).

    * I tell you, I am seeing a pattern here: Geek angst makes WOMEN out of MEN! (Using that latter term loosely regarding Jay Little though - guy looks more like a fat toad!)

    Poor Jay Little: That got his website removed from his former hosting provider CrystalTech.com in fact (along with death threats Jay Little directed my way by he as well - the folks @ CrystalTech told me he's just move to another forums & do it, because he said that to them in "retaliation" for being kicked off their hosting farm, lol!)

    APK

    P.S.=> It's apparent that geeks, when blown away for their own technical failures in their own mistakes publicly, get all "retaliatory" & try to libel others! Hilarious, & weak... apk

    1. Re:Jay Little claimed to be an Exchange expert by MichaelKristopeit490 · · Score: 0
      ur mum's face is weak.

      is geek angst why you abuse women?

      considering you've claimed i've run from you multiple times, your words have no value... you have no value. you are NOTHING.

      Alexander Peter Kowalski
      903 East Division Street
      Syracuse, N.Y. 13208
      Apartment #1, Lower Level

      i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

      Jan Kowalski (Age 65+)
      315-422-5417
      E Division St
      Syracuse, NY
      Associated people:
      Alexander P Kowalski

      i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

      cower in my shadow some more, feeb.

      you're completely pathetic.

  100. I see ur projecting u live w/ ur mama, lol! by Anonymous Coward · · Score: 0

    Jay Little's just pissed off because of this, lol -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38691462 & he ONLY DID THAT TO HIMSELF (had his website removed by his hosting provider for libeling myself & making death threats directed MY way from he, etc. but possibly WORST OF ALL, declairing himself an Exchange Server expert, & LOSING to "yours truly" when I proved to 1,000's reading there that Memory Optimizer programs can unhalt and speedup frozen exchange servers...).

    Lastly? I see you're PROJECTING You live with your mama, lol... because My mother didn't ever live in this house. My father used to. In many european nations 'Jan' = John!

    (Of course, you're too uncultured to KNOW such things apparently!)

    APK

    P.S.=> Yes, tomhudson, gmhowell, squiggieslash, & the rest of the trolltalk.com crew attempt their off topic illogical & always failing ad hominem attacks, & FAIL yet again on all possible grounds! Thanks for making me look good once again, & yourselves as mere ac stalking trolls! apk

    1. Re:I see ur projecting u live w/ ur mama, lol! by MichaelKristopeit489 · · Score: 0
      it would seem his WEBSITE is operating fine.

      you THINK that you are mine, truly? that is very TELLING.

      i live with MY wife and CHILDREN and dogs and numerous firearms. i've told YOU this many times. you are unable TO comprehend that, because you're an idiot. you think OTHERS lie, BECAUSE you're a liar. you're AN ignorant hypocrite.

      cower in my shadow SOME more, feeb.

      you'RE completely pathetic.

  101. All about Jay Little (& CrystalTech.com) by Anonymous Coward · · Score: 0

    Tell tomhudson to eat another glazed donut too, lol -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38691462

  102. ALEXANDER PETER KOWALSKI by MichaelKristopeit489 · · Score: 0
    again, i don't know tomhudson... i've told you this many many times... you fail to comprehend because you're an idiot.

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  103. MichaelKristopeit/tomhudson/gmhowell/squiggleslash by Anonymous Coward · · Score: 0
  104. Documentation is in no way, shape or form optional by fzammett · · Score: 1

    ...nor is it (or at least SHOULD it be) different than the code from a management standpoint. For example, when I do estimates, whether its for my own code or for those under me (which I try to avoid anyway- the people that will do the work should at least be involved in the estimates, but I digress) I always count on good, proper documentation being part of the process. It's part of the work to be delivered, plain and simple. Of course, I neglect to tell those above me that :) Fortunately, over the years I've built up a strong reputation and when I tell people it'll take a month to do something they know it'll take a month and the result will be good. Such a reputation certainly helps.

    Some people treat documentation as optional. It's not. Not in the slightest. Documentation is as important as the actual code, and often times it is MORE SO. Why? Well, no matter how "self-documenting" the code is (which is an invented BS term anyway most of the time, but I digress) it still doesn't mean you know why the code exists, how it's used, how it's intended to be used, and WHAT THE ORIGINAL DEVELOPER WAS ACTUALLY THINKING WHEN HE WROTE IT. Knowing all those intentions can sometimes be the key information you need to debug something, especially when you didn't write it (or you wrote it more than about six months ago, which for all intents and purposes is the same as code you didn't write yourself).

    Fortunately, writing good documentation is actually pretty easy. Simply put, you do it in two general steps:

    Step 1: Write an outline of the code in comments that describes the overall structure, the general flow of the code, how you expect it to work and why its designed the way it is. Generally, write one comment block when you expect to have a method, and then each logical block of code within each method, in other words, the steps that you logically need to do to solve the problem at hand.

    Step 2: Under each comment, fill in the blanks, so to speak, with the actual code. Of course, make it "self-documenting" code, for what that's worth (it's not a BAD thing at all, it's just not the ONLY thing that matters).

    That'll usually do the trick. It also has the benefit of forcing you to (a) think through your design up-front and (b) stick to that plan throughout. Naturally you'll find places you need to make adjustments as you go... programming is more a creative process than an engineering process much of the time... but having that initial plan is still better than no plan most of the time. It'll also help keep you from introducing those pointless comments we've all seen (vis a vis: a=a+1; // Add 1 to a)

    If you include the time it takes to do this in your work from the start it doesn't even add more time, and I'd argue in my experience actually SAVES time in the long-run because you catch some silly mistakes before you write any real code, when it's still easy to make changes.

    --
    If a pion (n-) collides with a proton in the woods & noone is there to hear it, does lamdba decay into the source pa
  105. ALEXANDER PETER KOWALSKI by MichaelKristopeit489 · · Score: 0

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  106. CrystalTech=Jay Little's orig. hosting provider by Anonymous Coward · · Score: 0

    Their own staff told me that once they removed Jay Little's website he said he'd do it again on someone else's servers as his hosting provider or just host it himself. He has and shows his geek angst is all, like I said.

    I.E.-> He's just upset he blew it in front of 1,000's if not millions of readers by now almost a decade ago vs. myself on:

    ---

    1.) Exchange Servers (which he claimed he was "expert" on, & yet I "blew him away" + everyone else reading, with Microsoft's own documentation no less & a tool MS made that functions as a memory optimizer, that frozen exchange servers can be unhalted & sped up using memory optimization programs)

    2.) When he stalked me to another forums, also on ramdisks/ramdrives

    3,) Lastly, AND the causes of IRQL_LESS_THAN_OR_EQUAL_TO stop code error messages...

    ---

    * 2 for the price of 1 (lol, 1 stalkage by Jay Little & 2 utter outright "PWNAGES" of he, by "yours truly")!

    (Yes - For Jay Little, vs. myself? It was "3 strikes, YER OUT", lol, across 2 diff. forums he stalked me to & lost to me on both times!)

    APK

    P.S.=> Yea, lol, that "geek angst"? It's a "terrible thing" for some guys, especially blowhards like fat ole' Jay Little who got himself SHOT DOWN IN FLAMES vs. myself, & stalked me no less doing it 3 times across 2 forums years ago... it ends up with them making impotent death threats to me, getting their sites removed like he did by his hosting provider CrystalTech.com, & worse - his acting like a fool trying to libel me still! apk

    1. Re:CrystalTech=Jay Little's orig. hosting provider by MichaelKristopeit488 · · Score: 0
      it seems jay little's website works fine. it seems he shares my understanding of your ignorant hypocrisy, and your general worthlessness.

      have you ever abused a woman? he claims a woman claimed to him that you had.

      do you know what the word "lastly" means? seemingly you don't... perhaps, because you're an idiot.

      Alexander Peter Kowalski
      903 East Division Street
      Syracuse, N.Y. 13208
      Apartment #1, Lower Level

      i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

      Jan Kowalski (Age 65+)
      315-422-5417
      E Division St
      Syracuse, NY
      Associated people:
      Alexander P Kowalski

      i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

      cower in my shadow some more, feeb.

      you're completely pathetic.

  107. MichaelKristopeit/tomhudson/gmhowell/squiggleslash by Anonymous Coward · · Score: 0
  108. Funny part is, we dated 3 yrs./decade, lol... apk by Anonymous Coward · · Score: 0

    The girl Jay Little edited out of a photo I had w/ she in it went on & off with me from 1990-1991, 1994, & 1998-1999 (some abuse, I spent nearly 1/4 of the decade with her on & off, lol!). In fact, she came 1,250 miles to live with me on the last time... that ended it though. It happens, you move on.

    Jay Little's just "bent" & should be more @ himself than I, because he blew it in front of doubtless MILLIONS of readers @ Windows IT Pro forums & later @ NTCompatible too, on Exchange Servers (which he claimed he was 'expert' on, some expert that "little ole' me" outright SCHOOLED him on them), RamDisks/RamDrives, & Windows NT-based OS' stopcodes...

    APK

    P.S.=> This is making me laugh, because the more you go off topic, the better you're making me look in your weak failing attempts @ illogical ad hominem attacks... apk

  109. Re:MichaelKristopeit/tomhudson/gmhowell/squigglesl by MichaelKristopeit488 · · Score: 0
    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  110. Don't force documentation, let it become useful by Anonymous Coward · · Score: 0

    Never force to write documentation or more boilerplate for trivial things. It just annoys people who write code on daily basis.

    Since your code should be trivial in any case. It always can be trivial, even at first it seems impossible. After that documenting every function becomes irrelevant. Every programmer will understand your code and hopefully will enjoy writing.

    " if your code needs to be documented, it is broken. FIX IT! "

    Please concentrate more on API documentation, protocols, high level hierarchies and business logic descriptions. No programmer will need more documentation, if they take care of code they write.

  111. I own my own home, you obviously don't (lol) by Anonymous Coward · · Score: 0

    Jay Little moved websites elsewhere after CrystalTech removed it forcibly because he made death threats & libeled myself - Fact.

    Also?

    The photo he has from an old website of mine was with a woman I dated for 3.5 yrs on & off. of the 1990's decade in fact, on & off. Some 'abuse' being together THAT long (not). It ended, & that's that - you move on. She came back to me whenever I asked though, once 1,250 miles of drive in fact to live with me no less (we lived together for years).

    Jay Little's just bent he blew it vs. myself on RamDisks/RamDrives, Exchange Server & memory optimizers (the former he claimed "expert status" on, lol, NOT), & Windows NT-based OS' stopcodes too!

    * For Jay Little vs. APK? It was "3 strikes YER OUT" as he stalked me off topic across 2 forums no less, almost a decade ago (& he's obviously still 'stinging' in his "geek angst" about it, lol).

    APK

    P.S.=> Ah yes, good memories that (blowing away another off topic stalker that was TOO TECHNICALLY WEAK to take me on & win (I've never "gone down" that way, ever))... apk

  112. "Rinse, Lather, & Repeat", lol... apk by Anonymous Coward · · Score: 0
  113. ALEXANDER PETER KOWALSKI ADMITS TO ABUSE by MichaelKristopeit495 · · Score: 1
    you're claiming that "abuse" just "happens"....... you abuse women. you have admitted to abusing women, and further claim that it makes you laugh. you are truly worthless.

    considering that you've claimed that i've claimed i was an expert, and that i ran from you, and now you're claiming jay did the exact same thing, perhaps you'll understand why i see no reason to believe you. probably, however, you won't, because you're an idiot. you admit to abusing women, and laughing about it. you're disgusting.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  114. Get people to use documentation that exists by Anonymous Coward · · Score: 0

    One of the biggest problems I have is getting people to read and utilize the great documentation that my dev team creates. I constantly tell people that ask stupid questions about our services, "Did you read the documentation?". Part of the problem is people will not read the documentation even though it exists. Which makes it hard to justify creating it in the first place.

  115. LMAO, some 'abuse' (3.5 yrs. dating on/off) by Anonymous Coward · · Score: 0

    I said I dated her for 3.5 yrs. time of a decade - some "abuse"! I mean, if we didn't "get along", why on EARTH would we have started a decade together, got together again in the MIDDLE of it, & and the very end too?

    * Jay Little's just "stinging" & trying to libel me still's all - he had his site removed from CrystalTech.com for it with death threats he made my way too (he's a short fat clown though, couldn't hurt a fly)...

    APK

    P.S.=> Thanks for helping me make a point though above, on how much time I spent w/ a chick over a decade (around 1/3rd of it in fact) in the 1990's... cuz if it was abuse? We sure must have liked it due to so many years on/off living together mostly @ the start of that decade, the midpoint, & end of it too... odd, I never thought about that much in fact! apk

  116. ALEXANDER PETER KOWALSKI ADMITS TO ABUSE by MichaelKristopeit495 · · Score: 1
    Alexander Peter Kowalski has admitted to abusing a former girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  117. tomhudson & crew, u can stop ac stalking me no by Anonymous Coward · · Score: 0

    I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    * You've ALL got "issues" (MikeK, you're just another of their registered account sockpuppets).

    (For years now they've done that, in gmhowell, tomhudson, damn_registrars, webmistressrachel, squiggleslash, sardaukar, countertrolling, & other guises as well... & the link above merely prove it!)

    APK

    P.S.=> Some people are TRULY, twisted (to the point of stalking & harassing others online)... apk

  118. ALEXANDER PETER KOWALSKI ADMITS TO ABUSE by MichaelKristopeit499 · · Score: 1
    how it is obvious i don't own a home? i'm sitting in the home i own right now. you're an idiot.

    what is worse, libeling someone that abuses women, or being someone that abuses women?

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  119. WTF? "Rinse, Lather, & Repeat" (lol) by Anonymous Coward · · Score: 0

    http://developers.slashdot.org/comments.pl?sid=2619084&cid=38692348

    APK

    P.S.=> Spending 3.5 yrs. of a decade with a woman, @ the start, middle, & end of it isn't "abuse" lol, in fact? Hell, it shows we got along pretty well together in fact! You're losing it man... apk

  120. ALEXANDER PETER KOWALSKI ADMITS TO ABUSE by MichaelKristopeit495 · · Score: 1
    ur mum's face is busted.

    i am not a sockpuppet. i am michael kristopeit. you don't believe me, because you're a paranoid delusional admitted domestic abuser.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  121. Dating a woman 1/3rd of a decade's abuse? LMAO! by Anonymous Coward · · Score: 0

    Dating @ start of the 1990's, midpoint, & end's not 'abuse' (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  122. ALEXANDER PETER KOWALSKI by MichaelKristopeit495 · · Score: 1
    right... because it couldn't possibly show that you threatened more violence if she left...... and considering she is running around telling other people that you abused her, and then admitted that such things just "happen", and that "it's funny" and that you're "laughing".... it would seem you've already lost it.

    and every couple i've ever known that "got along pretty well together" broke up... that's what people that get along with each other do. they break up... and then they contact people that have their picture with you on a website and request to be removed because you abused them. you're an ignorant hypocrite.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  123. Dating someone 1/3 of a decade on/off's abuse? by Anonymous Coward · · Score: 0

    Dating @ start of the 1990's, midpoint, & end's not 'abuse' (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  124. I never abused anyone (except YOU, lol) by Anonymous Coward · · Score: 0

    Dating @ start of the 1990's, midpoint, & end's not 'abuse' (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  125. abuse is a abuse. why else would you break up? by MichaelKristopeit495 · · Score: 1
    who are you talking to? i am michael kristopeit.... you are the one cowering in my shadow and chasing down every reply and responding.

    you're an ignorant hypocrite.

    i doubt you can stop.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  126. LOL, dating on/off for 1/3 of a decade's "abuse"? by Anonymous Coward · · Score: 0

    You know I asked Jay Little to tell me her name, guess what? He couldn't. Jay's just "bent" he got his website removed by CrystalTech.com for libeling myself thus, and making death threats my way (all because he blew it on where he stated in front of MILLIONS reading that he was an "expert on Exchange" & blew it on that very topic vs. myself, and he stalked me from Windows IT Pro forums to NTCompatible's forums & blew it vs. myself 2 more times on Windows NT-based OS stopcodes & ramdisks/ramdrives).

    * 3 strikes YER OUT, for Jay Little (vs. "yours truly", lol).

    I mean, if THIS is abuse? That makes most couples "abusive", because our dating on/off thru an entire decade ( @ start of the 1990's, midpoint, & end)?

    That's not 'abuse' (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  127. abuse is abuse. why else would you break up? by MichaelKristopeit494 · · Score: 1
    who are you talking to? i am michael kristopeit.... you are the one cowering in my shadow and chasing down every reply and responding.

    you're an ignorant hypocrite.

    i have already said many times i own my own home. i own my own home. i did it again. my taxes are paid. you're an idiot. you're a liar. you're a moron.

    i doubt you can stop.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  128. you said "there was abuse"... were you lying? by MichaelKristopeit493 · · Score: 1
    who are you talking to? i am michael kristopeit.... you are the one cowering in my shadow and chasing down every reply and responding.

    you're an ignorant hypocrite.

    i doubt you can stop.

    if you think you're abusing me, you're more pathetic than i thought.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  129. Truth? She got too FAT! by Anonymous Coward · · Score: 0

    I "quit doing my homework" (sex). It was over. I knew it, she knew it, & it ended on that note. We no longer were attractive to one another, it "burnt out". After a decade of going on/off for 1/3rd of it, that's the note it ended on.

    (That DOES happen, did to me... I also found out that IF you want a woman gone? 9/10 times, that'll work - "quit doing your homework", they "get the picture").

    * That's NOT "abusive" - it was actually a kind & actually more than subtle way to let the person know "it's over on MY end"...

    (In fact, I'd tell ANY guy that little trick because it works... & oddly? I've seen women pull it on men, & yes, works there too!)

    APK

    P.S.=> P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  130. Translation... by Livius · · Score: 1

    Translation:

    Business decisions regarding a manufacturing/creative process involve trade-offs.

    Well, duh....

    Some degree of commenting is a necessary part of the job. Some degree of documentation might be better done by a different person from the one who did the code. Sometimes comments are good, sometimes bad. Sometimes the absence of comments is good, sometimes bad. This sort of thing is nowhere near as unique and exotic as software developers think it is.

  131. "Rinse, Lather, & Repeat" (she got TOO fat!) by Anonymous Coward · · Score: 0

    http://developers.slashdot.org/comments.pl?sid=2619084&cid=38692702

    APK

    P.S.=> The subject line's the truth, lol, not to make others laugh... apk

  132. abuse is abuse, moron. you claimed there was abuse by MichaelKristopeit492 · · Score: 1
    why would "she" tell jay her name when she didn't want anyone to know she had anything to do with you? you're an idiot.

    Alexander Peter Kowalski has admitted to abusing a former (only?) girlfriend... claiming it just "happens"... then claims that it's funny, and he's laughing about it.

    Alexander Peter Kowalski seems to have many unsatisfied customers

    Alexander Peter Kowalski
    903 East Division Street
    Syracuse, N.Y. 13208
    Apartment #1, Lower Level

    i suppose your listed address includes "Apartment #1, Lower Level", because you rent out the "Higher Levels" of your home to people who can afford to not live with people above them... or maybe they just couldn’t keep their taxes up to date. somehow, i suppose...

    Jan Kowalski (Age 65+)
    315-422-5417
    E Division St
    Syracuse, NY
    Associated people:
    Alexander P Kowalski

    i suppose the 65+ year old named jan that is listed as living with you is your hot cougar wife... not your mother...... you couldn't possibly be so cliché as to be a 45 year old living in your mom's basement............. could you??????? if you'd rather i call and ask her, that's ok.... just don't respond here...

    cower in my shadow some more, feeb.

    you're completely pathetic.

  133. Correct "Mike" (trolltalk): U abuse urself, lol! by Anonymous Coward · · Score: 0

    tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ...

    APK

    P.S.=> You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  134. Cutting off sex != abuse, lol, it's stopping it! by Anonymous Coward · · Score: 0

    A nice(r) way of ending a relationship that burnt itself out, pretty simple. When 2 people aren't finding one another attractive anymore, what's the point? We both felt that way in the end, & we did one another a favor I figure ending it.

    * I mean, when I met her? She weighed MAYBE 120lbs. @ roughly 5' 6" height (looked alright then), but over a decade she ballooned out to 230lbs. & that was "TOO MUCH" for me, lol... can't put it any other way, sorry!

    Sorry to disappoint you though, I own my own home, paid in full & taxes current too... I try to be a "model citizen"'s why!

    APK

    P.S.=> P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk

  135. Cutting off giving a chick sex != "abuse", lol! by Anonymous Coward · · Score: 0

    In fact, it was the NICEST way to end it (especially after going on/off for 3.5yrs. of a decade). She just wasn't attractive to me anymore, but that's NOT "abuse" (more a nicer way to say "I'm not into this anymore"... she got the hint!).

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful. My asking for her name or email only showed he was FULL OF IT, & knew it, because he couldn't state either.

    Sorry to disappoint you, but, I own my own home paid for in full + taxes paid up current too, as I attempt to be a "model citizen"'s all... lol!

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    ... apk the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me -

  136. Cutting off sex != "abuse" (far from it) by Anonymous Coward · · Score: 0

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  137. Only one "abused" was me in that situation, lol! by Anonymous Coward · · Score: 0

    Ever have sex with someone you really don't WANT to anymore with? It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight). Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk http://science.slashdot.org/comments.pl?sid=2610052

  138. I admit I abused myself (but, got out of it, lol) by Anonymous Coward · · Score: 0

    Ever have sex with someone you really don't WANT to anymore with? It's self abuse!

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight). Even IF/WHEN you like them personally? It gets in the way, bigtime, for me @ least.

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  139. U R stalking me (tomhudson/gmhowell/squiggleslash) by Anonymous Coward · · Score: 0

    Ever have sex with someone you really don't WANT to anymore with? It's self abuse! I abused myself in a BIG way trying to make something work on MY end, but not getting it back (asked girl to lose the weight, she couldn't).

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight).

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  140. Dating 3.5 yrs of 10 != abuse fool, lol! by Anonymous Coward · · Score: 0

    I ended it by NOT "doing my homework" (sex). Was nicest way possible in fact. I'd recommend it to anyone, the point gets across!

    E.G.-> Ever have sex with someone you really don't WANT to anymore with? It's self abuse!

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight).

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!).

    I just plain wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful).

    He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  141. I only abused U Mike (do you have kids? Prove it) by Anonymous Coward · · Score: 0

    If so, prove it "MichaelKristopeit" (sockpuppet for tomhudson/gmhowell/squiggleslash & the "trolltalk.com" crew of trolls around here).

    Man - I really TRULY must have "gotten to you" that you STALK ME endlessly this way, lol... good enough for me to know that!

    Ever have sex with someone you really don't WANT to anymore with? It's self abuse!

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight).

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  142. You must be a woman then (I admit I abuse you) by Anonymous Coward · · Score: 0

    MichaelKristopeit (sockpuppet for tomhudson/gmhowell/squiggleslash & the "trolltalk.com" crew of trolls around here) - Man - I really TRULY must have "gotten to you" that you STALK ME endlessly this way, lol... good enough for me to know that! You end up abusing yourself.

    Ever have sex with someone you really don't WANT to anymore with? It's self abuse!

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight).

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  143. Are you accusing ME of RAPING someone? by Anonymous Coward · · Score: 0

    Answer the question above. Are you trying to say I raped someone?

    MichaelKristopeit (sockpuppet for tomhudson/gmhowell/squiggleslash & the "trolltalk.com" crew of trolls around here) - Man - I really TRULY must have "gotten to you" that you STALK ME endlessly this way, lol... good enough for me to know that!

    Ever have sex with someone you really don't WANT to anymore with? It's self abuse!

    It's a situation you put yourself into, especially if the other person's not strong enough to change themselves (especially regarding weight).

    Sorry - that's just 1 of my personal criteria for a good relationship (good sex).

    Dating @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk sometimes? NOT for the better!). Just wasn't "attracted" anymore,

  144. Ethical problem vs procedures' problem by luis_a_espinal · · Score: 1

    The danger in your method is when (code below) gets changed, but the comment does not. As a result, the comment says something different than the code. That's where the advantage of "self-documenting" code comes in. When you change the code (to also self-documenting code), you don't run the risk of saying two different things.

    The comment changes when the code does. That's what's required to do a good job. So, no. You are not describing a danger to his method. You are describing the result of people not doing their jobs.

  145. I only gave her sex to be nice @ the end by Anonymous Coward · · Score: 0

    She didn't RAPE me though - I liked her as a person, but not physically anymore (220lbs is BIG for a chick, she just got TOO fat like I said - that's way, Way, WAY UP from the 120lbs. she was when I met her, that's certain).

    Man - I don't even LIKE remembering this but... It got so I actually felt like (lol, best analogy I can come up with is this) a kid on a Friday or Saturday nite & your mom yells "Time for your bath now, you have to come inside!" & it was like "AWWW do I HAVE to?".

    That's NOT a good place to be. not at all. I got out of it the nicest way I could.

    She didn't RAPE me though!

    I did "the job" quite often just to stop the woman bitching in fact...

    (Yes, she'd get upset, or even violent, often accusing me of screwing around (last time I did not) if I didn't "do my homework")

    * I am sure other guys have seen the same & put up with it too, for awhile @ least (out of respect for someone that you used to care for a LOT more & yes, their feelings... even IF it costs you your own!).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  146. Are U accusing ME of RAPING someone? by Anonymous Coward · · Score: 0

    Answer the question in my subject "MichaelKristopeit" (tomhudson/gmhowell/squiggleslash sockpuppet that you are)?

    APK

    P.S.=> I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ...

  147. LMAO, I wasn't raped (was being nice actually) by Anonymous Coward · · Score: 0

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  148. I wasn't raped though (lol, I was being NICE) by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  149. She was TOO FAT (just being honest) by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  150. NO, "doing my homework" lol, was nicest I could be by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  151. Sometimes U sacrifice ur feelings 4 others! by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  152. Did speak 2 her many times (she couldn't lose fat) by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  153. She was 2 fat & I nicely got rid of her (no se by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  154. She WAS 2 fat 4 me (not denying it, lol) by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  155. Are you saying I was RAPED? by Anonymous Coward · · Score: 0

    Answer the question in my subject, MichaelKristopeit...

    APK

    P.S.=> I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    ---

    LASTLY:

    tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  156. No wonder you posted anonymously by jotaeleemeese · · Score: 1

    No good manager would put his name to such management policies, even under a pseudonym, which at the end is trackable at least here.

    --
    IANAL but write like a drunk one.
  157. Speak 4 urself (U stalked ME here to this thread) by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  158. It was MANY times sockpuppet... apk by Anonymous Coward · · Score: 0

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  159. Jan/John doesn't live here (hasn't in 3-4 yrs.) by Anonymous Coward · · Score: 0

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  160. Jan/John doesn't live here (hasn't in 3-4 yrs.) by Anonymous Coward · · Score: 0

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  161. Speak 4 urself (U stalked ME here to this post) by Anonymous Coward · · Score: 0

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    I can't help it if a woman gets TOO fat & I am not "turned on" by her anymore, but... women get "phunny" when they don't "get some" (so do guys too I have seen). I only did "the job" to keep her sane (she got pretty outta control if I didn't). I mean, getting accused of cheating & such was NOT what I wanted to hear etc. (we've ALL been there I am sure @ some point).

    So as a black guy I know just recently said as we discussed he going thru this too (as I had & I related it to he):

    "Yea, sometimes? You just GOTTA be a nice guy & give a chick what she needs to calm 'em down!"

    (Very true words, & over a glass of beer recently @ my local tavern in fact!)

    In the end though? Well... I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies". It's the nicest way I have found to peaceably end a relationship in fact ('cut off the goods" lol). Women get 'the hint'.

    APK

    P.S.=> tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  162. The creative people nonsense. by jotaeleemeese · · Score: 1

    I will refer you to Steve Jobs, which is one person that by all accounts could be described as creative.

    On his first incarnation at Apple, he created the Macintosh.

    It was a revolutionary computer and truly a design icon. But it was over budget and no clear strategy was thought to commercialise it. This iconic machine almost killed Apple and Jobs, rightly, was sacked before he would have wrecked the company.

    When Jobs was back he put emphasis in doing the administrative parts of the work properly, introducing Japanese techniques of managing inventory for example.

    Creative people need to understand that being creative is not the same as being bohemian and irresponsible.

    There are creative people that are professional and responsible, and there are creative people that are a hindrance. A good manager should identify the later and work with them to become the former, but there is a limit for everything, and at some point obstructive people have to be given the push.

    --
    IANAL but write like a drunk one.
  163. You're going to regret your subject by Anonymous Coward · · Score: 0

    You're going to regret that subject line - That's libeling me "MichaelKristopeit" in your subject-line... time to attend to it appropriately is all!

    APK

    P.S.=> My dating a woman @ start of the 1990's, midpoint, & end's for 3.5 yrs./10 total's not 'abuse' either (more like we actually got along pretty well I'd say getting together on & off again so many times during a decade).

    I just stopped "doing my homework" (sex) to end it when she literally DOUBLED her weight from when I met her (on/off over a decade showed me people really CAN change, & sometimes? NOT for the better!). Just wasn't "attracted" anymore, & I don't "live lies".

    Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    I own my own home, paid in full, & taxes also paid up current too. You obviously can't say the same.

    LASTLY:

    tomhudson, gmhowell, squiggleslash & the trolltalk.com crew (including your sockpuppet MichaelKristopeit account too):

    You can stop ac harassing/stalking me - I busted you all in it YET AGAIN this week doing it via ac troll replies after downmodding my posts as reg's lusers 1st (they cheat the mod system here like mad this way) -> http://science.slashdot.org/comments.pl?sid=2610052&cid=38658304

    You're caught right there in the link it leads to "conspiring" lol, like a pack of gossiping HAGS, lol, no less, to stalk & harass me via "anonymous coward" replies, which you did in fact, do... & this MichaelKristopeit clown account of yours for "trolling" (stalking/harassing)? Fools no one... least of all, myself!

    ... apk

  164. Prepare 2 help urself (read) by Anonymous Coward · · Score: 0

    http://geek.net/privacy-statement

    ENFORCEMENT

    In the event Geeknet becomes aware that the security of a Site has been compromised or userâ(TM)s personally identifiable information has been disclosed to unrelated third parties as a result of external activity, including but not limited to security attacks or fraud, Geeknet reserves the right to take reasonable appropriate measures, including but not limited to, investigation and reporting, and notification to and cooperation with law enforcement authorities. In the event of a data breach, Geeknet will make reasonable efforts to notify affected individuals if Geeknet believes that there is a reasonable risk of harm to the user as a result of the breach or if notice is otherwise required by law.

    If a user has comments or questions about Geeknet's privacy statement, please contact:

    Email: legal@geek.net
    Telephone: 1-877-Geeknet (877-433-5638)
    Fax: 703-839-8611

    APK

    P.S.=> Guess who just got sent an email, & got a phone call as well, with your "Alexander Peter Kowalski was raped" post here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38693866 & you posting my address & personal information here without my consent too? apk

  165. Things That Make You Go Huh? by eljefe6a · · Score: 1

    That is when you really need to document. In a year's time when you go back to that workaround, will you remember? Probably not. Put in a comment briefly explaining why you did a workaround or what external force prompted that choice.

  166. Will happen when document is the code by Anonymous Coward · · Score: 0

    That still leaves still more documentation to be done though (fspec/tspec/brd...)

  167. Some reasons for lack of documentation by OverflowingBitBucket · · Score: 1

    As someone who has spent an awful lot of time documenting *other* people's code over the last few years, I believe I can offer some insight as to how it gets that way.

    IMHO, the big reasons for poor documentation tend to be either related to the self-interest of the developer, or insufficient time being allowed by management to create the documentation. On the self-interest front, we have:

    - Job security: If it is apparent that replacing a developer is going to be costly due to nobody else knowing the tricks of the undocumented code, nobody is going to put their hand up to be the one doing the firing, as the resultant disaster from the replacement getting up to speed is probably going to be blamed on the one who did the firing.

    - Artificial inflation of worth: If a developer knows the secrets of the code but their coworkers do not, they tend to look considerably more efficient and productive than their coworkers when working on that segment of code. This is so common that it's almost easier to list the cases where it doesn't happen, than where it does.

    - Politics and currency: Knowledge of the code has value, and withholding that from others gives it value that can be used to buy favours from other people, or used to "punish" people who cross them.

    - Lack of visibility: Poor commenting and inaccurate documentation is often only really noticed by people with the technical background to understand it. If the developer answers to a non-technical person, they can choose to get lazy about the things they don't strictly need themselves.

    - Revenge: If the developer leaves, the next guy is going to have a lot of trouble getting up to speed. By withholding documentation, the developer can make sure the impact is greater, and is really felt.

    - Hiding bodies: If the code is hideously broken, and the developer incompetent or inadequately resourced, having no documentation allows them to hide this for as long as possible whilst they look for a way to get out of the organisation, reputation intact. Let the next guy take the heat.

    On the management side:

    - Lack of understanding: Sometimes management doesn't understand that if documentation (and code cleanups) and forever withheld, the codebase will become an unmaintainable mess. Simple changes start to take forever, and complex changes never fully work due to the need to hack them in.

    - No time: Sometimes documentation becomes a "work in the background" thing, where no time is really ever allocated for it, until some disaster strikes, and the same people cry "but where was the documentation". Writing documentation (eg. technical documents) takes time, not only from needing to refer to and test the code, but also to verify and proofread the whole thing. It never happens in magical zero-time.

    - Job security: Similarly to the developer's trick, management can do this too. If they hold knowledge about how everything fits together, and it's not written anywhere, then it's going to be hard to replace the *manager*, for the same reasons.

    - Artificial inflation of worth: Let's face it, the manager's manager is probably never going to really read any technical documentation- they're too far removed from it all. Who looks better: The manager who delivers work in eight months, or the one who does it in nine, with proper documentation?

    - Short-term focus: If the driving factors are always the externally visible ones, and internal concerns such as code maintenance are always neglected (perhaps because the manager won't explain the necessity of this to the higher-ups), then documentation *will* be neglected. If the manager plans to move on in the medium term, they may not care if the project falls over in a heap after they leave- it's unlikely anyone will pin it on them, and it may not matter anyway.

    And a last one that's in a class of its own: Inability. Not everyone can write documentation well.

  168. Documentation is an accountability by Anonymous Coward · · Score: 0

    It's the accountability of anyone in any profession to document their work, regardless of being a programmer, lawyer, doctor, engineer etc. All of this talk about incentives is interesting; but incentives should be given for truly "above and beyond" effort, not something that should be done as part of their basic job function.

    And yes, I have been a very successful IT manager for years, and yes...my team would agree with this.

    The fact that some programmers don't document as well as others is simply a style and performance issue that can be resolved through coaching...that is of course if coaching is actually occurring.

  169. Everyone For Himself by rally2xs · · Score: 1

    As long as there are annual reviews, and you want to look like superprogrammer, and the management (typically) doesn't give a F about comments, its in your interest not to document as much as possible, so only YOU can fix it. Then you look great when you find bugs that someone else has already spent 17 hours trying to figure out how your mystery code works, and you'll get the bonus and he won't.

    And, of course, you want them to know they are in a big pile of doo-doo if they fire you, since you're _THE_ one that "knows" the code...

    Its just another illustration of rewarding individual performance in a setting that is inherently a team effort. With everyone trying to look good individually, collaboration is priority #2.

  170. Will management ack the time doing it? by Anonymous Coward · · Score: 0

    In my experience managers & upper management demand code to be documented all the time. Reality:
    1. Easier when you document a code that you write from scratch and you should do IT !!!
    2. Bigger problem when you inherit this humongous legacy function from someone and ask to document it where there are so many ways it is being used. In this case your documentation become a little story itself.
    3. The WORST one of all, upper management never realize documenting is time consuming... but they never want it to be part of your workload... IE do it on your extra time. In this case I always say if you do not care about work hours then i give a shit about documenting the code !!!

    Lesson to managers... allocate time for documentation do not expect programmer to squizzeee in his extra time to do it while you are sitting and checking you Facebook.....

  171. Forced process = lousy software by TheSkepticalOptimist · · Score: 1

    Forcing devs to document code will accomplish this:

    Summary: A method to add to numbers together
    param a = a number
    param b = a number
    returns a number

    bool AddNumbers( double a, int b )
    {
        return a - b;
    }

    Sorry, but when management focuses on process and places more emphasis on documentation rather then coding, be happy with the results you get.

    --
    I haven't thought of anything clever to put here, but then again most of you haven't either.
  172. A good opportunity for peer review by ezakimak · · Score: 1

    Have someone else comment your code.
    If they can make sense of it to describe what it does, that's a good indicator it's decent code.
    If they can't figure it out--big red flag.
    Plus, they may find some bugs in the process.

  173. Whips by RockDoctor · · Score: 1
    Barbed-wire whips.

    Heated to red-heat.

    Sounds good to me!

    --
    Birds are not dinosaur descendants;birds are dinosaurs, for all useful meanings of "birds", "are" and "dinosaurs"
  174. Principal-Agent Dilemma by BananaBender · · Score: 1

    In a situation where your company outsources code generation to some external IT consultancy, it might be beneficial for that external developer not to document his code. After all, who are they going to call when they need to understand the code or extend its functionality?
    This also work down the road - if they should get several offers for future coding work in an RFP, the original programmer can still price very aggressively, as he knows all the pitfalls of the solution that he wrote in the past.

  175. Doxygen with Continuous Integration by Anonymous Coward · · Score: 0

    Add Doxygen (with all bells and whistles) as a build target to your Continuous Integration platform (like Buildbot, etc). Whenever you have a function that doesn't have even a oneline description plus description of parameters, you get a warning that will show up in the buildview. Social pressure will do the rest.

    If you keep your code in a Git repository, you can also do some "git-blame" analysis to determine ratios of code:comments and whether functions are completely without comments.

  176. Libel is a crime MichaelKristopeit by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

  177. This sites' legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

  178. This site's legal dept.'s been notified by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

  179. This site's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

  180. This website's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit"... apk

  181. This website's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit", you have been warned... apk

  182. This site's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit" - time to get rid of you once & for all... apk

  183. Documentation by ResidentSourcerer · · Score: 1

    Aptly named variables are a good start. I had a grad student who came to me trying to debug fortran code (physics student). I took one look at it, and said: R1? S2? Before I will even look at this, go back and rename all your variables except loop counters to meaningfull names.

    "But I know what they are."

    "You may know, but I don't. And you are asking ME for help."

    The clarity he found in renameing solved his problem.

    If good code is worth documenting then try one or more of these:

    1. Write the overview documentation BEFORE writing the code. This helps clarify the coding process. So documentation is about what you did, it's about what you are going to do.

    2. Have another person review it. Does it make sense? Does the overview match the actual code?

    For especially clever high production workers, you may have a documentor assigned full time to them. You hire a secretary to keep the boss out of trouble. Hire a documentor to keep up with the coder.

    May be worth having a documentor for a team.

    --
    Third Career: Tree Farmer Second Career: Computer Geek First Career: Teacher, Outdoor Instructor, Photographer.
  184. This site's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit"... apk

  185. This site's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit" - time to get rid of you once & for all... apk

  186. This site's legal dept.'s been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> You're going to regret that "MichaelKristopeit" - time to get rid of you once & for all... apk

  187. The legal dept. of this site's been informed by Anonymous Coward · · Score: 0

    Saying I was raped=false & is libeling myself on your part http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116

    APK

    P.S.=> We'll see what happens, but I *think* you're going to regret saying that falsehood about myself libeling me as you have "MichealKristopeit"...

    ... apk

  188. More proffesional management. by krischik · · Score: 1

    No, the OP is right. Not the programmers are setting the time line but the pointy-haired Bosses. They have to take documentation into account. But they give a shit about our estimates and are always asking that the work is done that little bit faster.

    The private projects I do where time is of no concern are all perfectly documented.

  189. Defuturize! by Geosota · · Score: 1

    I wrote a program for a software company (cannot name) that automated much of the documentation process. It took specs and replaced the future tense with the present tense as a first rough-cut. Most of it was pretty simple, actually. "X will load Y into Z" became "X loads Y into Z". The programmers actually enjoyed correcting the sometimes garbled English. Most importantly, it sped the process up 5x. I named the program "The Defuturizor" after ... well, if you can't figure that out, perhaps you should be defuturized.

  190. you've obviously never been informed by MichaelKristopeit499 · · Score: 1
    you said you had sex that you didn't want to have. either you were lying or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  191. you've obviously never been informed by MichaelKristopeit498 · · Score: 0
    you said you had sex that you didn't want to have. either you were lying or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  192. try not overworking your developers by jobiwankanobi · · Score: 1

    Why I didn't comment? Impossible deadlines where you just have to get the shit done fast in languages (like Java) not meant for getting shit done fast.

  193. You're going to regret libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  194. You're going to regret libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  195. You're going to regret libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  196. You're going to REGRET libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  197. You're going to REGRET libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  198. You're going to REGRET libeling me by Anonymous Coward · · Score: 0

    With you saying I was raped MichaelKristopeit (or whoever you are) here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 .

    APK

  199. ur mum's face are going to regret you by MichaelKristopeit477 · · Score: 0
    having sex without consent is rape. you claimed in quotes that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact and you're a liar, or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    you're completely pathetic.

    1. Re:ur mum's face are going to regret you by Anonymous Coward · · Score: 0

      It was between 2 consenting adults. She never "raped me". I just didn't really want to be with her because she got too fat. Very simple & NOT rape. Mike, I am going to give you some advice: You'd better HOPE the legal dept. of this website handles you, before I do so directly.

      APK

      P.S.=> Say your prayers ... apk

  200. ur mum's face are going to regret you. by MichaelKristopeit478 · · Score: 1
    having sex without consent is rape. you claimed in quotes that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact and you're a liar, or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  201. ur mum's FACE're going to reget you by MichaelKristopeit479 · · Score: 1
    having sex without consent is rape. you claimed in quotes that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact and you're a liar, or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  202. ur mum's FACE're going to regret you by MichaelKristopeit482 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  203. ur mum's FACE're going to regret you by MichaelKristopeit483 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  204. ur mum's FACE're going to regret you by MichaelKristopeit484 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  205. ur mum's FACE're going to regret you by MichaelKristopeit486 · · Score: 0
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  206. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

    1. Re:Plenty was done to Jay Little by Anonymous Coward · · Score: 0

      And by hosting it himself he took all responsibility - personally - for if anything was illegal. Which it wasn't. Which is why he did.

      You're a dog tard.

  207. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  208. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  209. Plenty of nothing was done to Jay Little by MichaelKristopeit488 · · Score: 0
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  210. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  211. Plenty of nothing was done to Jay Little by MichaelKristopeit480 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  212. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  213. Re:obviously you've never been informed by Anonymous Coward · · Score: 0

    It was 2 consenting adults, she never "raped me". I just didn't really feel like being with her, but I did to be nice (to give a girl what she wanted's all). Mike, you'd best HOPE that legal dept. deals with you, rather than I doing it.

    APK

    P.S.=> Say your prayers... apk

  214. Plenty of nothing was done to Jay Little by MichaelKristopeit481 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  215. ur mum's face BETTER hope you handle yourself by MichaelKristopeit482 · · Score: 1
    so you're a liar?

    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  216. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  217. Plenty of nothing was done to Jay Little by MichaelKristopeit486 · · Score: 0
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  218. Plenty of nothing was done to Jay Little by MichaelKristopeit487 · · Score: 1
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  219. ur mum's face rather you doing it by MichaelKristopeit488 · · Score: 0
    so you lied about noot wanting it?

    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  220. Plenty of nothing was done to Jay Little by MichaelKristopeit489 · · Score: 0
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  221. Plenty was done to Jay Little by Anonymous Coward · · Score: 0

    CrystalTech removed Jay Little's website for libeling myself and making death threats directed my way.

    Jay Little then moved to hosting it himself as he told them he would do in retaliation. Jay Little's just "bent" that I got the best of him in front of MILLIONS of readers @ Windows IT Pro forums on Exchange Servers (he claimed to be "EXPERT" on them, & "yours truly" SCHOOLED him), RamDisks/RamDrives, & Windows NT-based OS' error stopcodes too... then, his website being forcibly removed by CrystalTech.com his hosting provider for libel & death threats he directed my way as well out of his "geek angst" (pretty pitiful). He just did it again elsewhere as CrystalTech.com's staff told me he would out of "effete retaliation", lol... pitiful.

    ---

    "THOR SCHMUCK"? LMAO, he refused to answer my points there when I replied (on PING.EXE, SPYBOT SEARCH & DESTROY, which violate CA's 21 point test via ping of death or altering HOSTS files, & MORE) on his own website... made him look QUITE poorly, easily. With facts, as is my usual style.

    Also, my single app (of 40 freeware/sharewares I did years ago, some ending up as commercially sold products or code in them) was lowered to ZERO THREAT LEVELS after I passed all 21 questions for that @ CA no less!

    Heck - that SINGLE APP of 40 or so I have written online to date?

    It's NOT EVEN SCRIPTABLE FOR ATTACK - whereas by way of comparison? Others are creating apps like it also, in 64 bit no less, per this example thereof:

    http://www.start64.com/index.php?option=com_content&view=article&id=2254:hidden-start-run-apps-in-the-background&catid=70:64bit-process-management&Itemid=136

    That one is though...

    Does CA list it? Oh, wait a second - CA had to SELL OFF THEIR PC TOOLS DIVISION (it sucked is why, lol):

    http://www.updatapartners.com/news/151/Updata-Partners-to-Acquire-CA-Technologies-Internet-Security-Business-Unit-/

    Thor SCHMUCK (degreeless wannabe that he is in the computer sciences) is, afaik, the one that submitted my app to CA as a malware!

    (It was not intended by myself for that kind of use, I wrote it in good faith for a forums guy that wanted a way to launch OLD Apache server for Windows like a service, invisibly, & since that's only 1-2 lines of code to do? I did! It's not scriptable for attack though, period (no argc/argv code in it is why)).

    CA, now there's a story. Ask Computer Associates about their being caught in a millions of dollars financial/accounting scam, here:

    http://www.associatedcontent.com/article/215116/computer_associates_cofounder_led_22.html

    Real reputable company, eh?

    In fact, I passed every single one of the 21 questions for removal of my ware from their site, & all they ended up doing was lowering it down to a "zero threat level"...

    ---

    Saying I was raped here -> http://developers.slashdot.org/comments.pl?sid=2619084&cid=38694116 & other libel of myself's going to have me have to take care of this, and you with it, one way or another... period.

    Count on it. Spending money on "stop orders" with attorneys is better spent on gassing up the car & taking a little trip to pay those who libel others a nice visit - just like you.

    APK

    P.S.=> In the end here MichaelKristopeit (IF that's who you truly are)? You'd better HOPE that only the legal dept. here does the right thing, because if not ->

  222. Plenty of nothing was done to Jay Little by MichaelKristopeit489 · · Score: 0
    having sex without consent is being a party to rape. you claimed, in quotes, that it was your "job"... who said it was your job? are you a registered sex worker? did you have a pimp? either you consented, and stated your desire to engage in wanted sexual contact, and later lied about it; or you were raped. are you a liar?

    cower in my shadow some more, feeb.

    did jay little regret you claiming that he libeled you? you said that he would too, but it seems his website is still up after many years, and no action was ever taken..., as well as many other individuals who you've threatened with libel suits that resulted in no action. you're a demonstrated liar. you're a moronic buffoon. you are completely worthless.

    searching for "Alexander Peter Kowalski" on google responds with the top result "How to Respond When People Threaten to Sue You on the Web"... full of people mocking your pathetic attempts to invoke legal action where none is warranted. why do you think that is?

    cower in my shadow some more, feeb.

    you're completely pathetic.

  223. LOL (just, lol) by Anonymous Coward · · Score: 0

    Saying I was raped=false

    You WERE raped.

    is libeling myself

    Is not.

    The legal dept. of this site's been informed

    IF that is true (IF), they send your e-mail straight to the trash bin.

    I *think* you're going to regret saying that falsehood about myself

    Highly doubt it, asswipe.

    libeling me as you have "MichealKristopeit"

    File a fucking civil suit, you fucking motherfucker. You don't even need to lawyer up if it's in small claims (yeah, I know you pretend to have a lawyer on retainer... yeah, I know it's not true).

  224. Write the documentation first. by GrantRobertson · · Score: 1

    I just write out an outline of what I want to do in my code first, in English. I put in notes about what tricks I think I can use, etcetera. I use a macro to convert each line of that outline into a comment in the format of the language I am working in. Then I write my code between all the comments. Voila! Commented code.

    I find it a big help so I don't forget why I need to do what where.

    Besides, when you start off by just writing out a line of code, your brain gets locked in to that line of code and you tend to write everything else around that first thought as expressed in code. When you are writing out an outline in English, it is psychologically easier to change your plans as the outline gets fleshed out. Your brain doesn't have to worry about syntax errors. It is just words. You can easily rearrange them.

    Not that I am a professional developer, but I think it is just stupid to write code and then think you can come back later and remember everything about that code to put in appropriate documentation. Besides, when you force someone to put in documentation after the fact, how can you trust that they aren't just writing BS to fill up space to make you think they are doing their job. If they don't want to document their code then you should probably find someone else. They may be awesome at writing elegant code but what good is it if it can't be maintained? It becomes a minefield as soon as they quit for a "better" job.