|
I agree documentation tools are pretty much non existent, pity would really help poor souls like me.
I think my biggest problem is my grasp of the English language. One tends to fear what one does not understand.
You, Sasha, Nish and others have a writing style that I envy.
I excel in other areas; trivia, kick the can, distance spitting, etc.. 
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
Self Documenting Code... I always thought it was a buzz word way to get out of using comments/documentation, I have hardware projects to take over that were self documenting apart from the input, power amp it wasn't! same with code 'Oh I see what is being done, but why?' is a common in my experience! 
|
|
|
|
|
I'm finding that with hardware I need to document also but in a different way; I keep notes, schematics, images of the final product, etc. then when I go back some time later it is a lot easier to remember seeing that I have the CRS syndrome.
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
Quote: kick the can, distance spitting
Ow! you got me TWICE
Life is like a s**t sandwich; the more bread you have, the less s**t you eat.
|
|
|
|
|
You don't get paid enough to document code.
I'm looking at very sparse data array of informative statistics about contacts from my landlord warning me of imminent water shut offs. I see four notices over a years' time, and only two of them in which the water was indeed shut off.
How is this data? It's uninteresting PLUS it's only pseudo valuable in that it contains only partial information about what it's entitled to contain.
Perhaps if the water really did get shut off, I'd be happier about being notified.
|
|
|
|
|
RedDk wrote: You don't get paid enough to document code.
I don't get paid anything for writing code, I do it for the fun of it.
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
|
Mike Hankey wrote: I don't get paid anything for writing code, I do it for the fun of it.
Right, they pay me to do it for them.
Although, most of what they have me doing is SSIS and that's not code.  There has been some coding fun this week as I have been working with the TFS API.
|
|
|
|
|
I have enjoyed writing doco precisely once in my entire life, in the early 90s I got paid approx $5k to build an app. In the late 90s they wanted to rewrite it into Delphi, when I refused they asked me to write the technical spec so their coders could work from it, I charged $20k and laughed all the way to the bank.
It is the only time I think I have actually done a good job of doco, they got their moneys worth.
Never underestimate the power of human stupidity
RAH
|
|
|
|
|
Mike Hankey wrote: Why is it that we as programmers hate to document?
I wonder if there is a correlation between the dislike for wanting to write documentation and writing research papers. I don't care for writing documentation and I never cared much for writing research papers in college. I had to do it, but I didn't like it.
Thus, my hypothesis is, if you like writing in general, you will not mind writing documentation. 
|
|
|
|
|
When I first started in the industry, the standard was that documentation was to be completed before the first line of code. Some refer to that method as the waterfall method. Today, you seldom see documentation; or, what little there is seldom reflects the product for which it is written.
As a basic rule of thumb, write your documentation for an eight-year-old. (I used to have my daughter do the final edit of my documentation until she was eleven.)
|
|
|
|
|
Member 10707677 wrote: documentation was to be completed before the first line of code
That's just a specification. I've seen a few of those, read them, said "OK here's a better way to do that", and wrote something that actually made sense instead.
Where I am now I just keep saying "documentation is out of date as soon as it's published".
|
|
|
|
|
I've once read some self documenting code. I hit a point where I said to myself "that is just plain wrong logic". When I brought it to the attention of my manager, we couldn't change it because it was written per the spec document. I asked to see the spec document. I conceded the code did exactly what the spec said it should. She thought the matter was closed when I added "It's too bad it isn't doing what it is intended to do." We spent another hour going though the code to prove that what I saw in fifteen seconds was true. (fixed by changing "<" to ">" or vice versa)
|
|
|
|
|
Your mention of self-documenting code reminds me of my university days. One of my professors threatened to fail us if we didn't include comments in the source code. This was in the age when punch cards were still being used, so comments were a nuisance. One of the students turned in a final project with a single comment "RUN PROGRAM" as the first card of the deck. The result, when run, was a listing of the source code with accompaning commentary. Needless to say, he passed.
|
|
|
|
|
Member 10707677 wrote: documentation was to be completed before the first line of code. Some refer to that method as the waterfall method.
There seems to be different definitions for that method. Some studies have found the most successful projects used a combination of waterfall and agile methods combined. Waterfall starts with an overall plan and relationships. Those ideas are then documented separately breaking it into more plans and relationships. If you keep going like that you can easily get bogged down. Once you get down to about two-three levels, I can see the benefits of abandoning waterfall at that point and going to agile to get early results of the pieces documented to that point.
|
|
|
|
|
Early on I spent a great deal of time on documentation only to have it never referenced. I don't mind doing training materials because they are used, but developer docs are a waste of time because devs don't look at it.
|
|
|
|
|
For one thing, managers generally don't factor documentation time into coding deadlines, so if you spend time documenting it can look like you aren't getting your "real" work done fast enough.
But the larger problem is keeping it up-to-date. You may have time to do the initial documentation, but are you going to have time to update it with every change? What about when another team member ninja-edits the code, are you going to regularly check and make sure the documentation still matches the code?
I used to try very hard to have good documentation, but I found it to be hopeless. You end up with outdated documentation, which is often worse than no documentation at all. I don't buy the "code should document itself" argument, but for practical purposes that's where we're at, even if you have documentation you still have to go through the code and make sure the documentation isn't lying to you.
Edit: There's one time when documentation should be mandatory: when you are leaving a job. You likely aren't going to be needed to meet a coding deadline during your last two weeks, so spend that time documenting the systems you've been responsible for so the next person has something to go by when they pick up those systems. It's good karma, and that's when documentation is really needed and will get read.
modified 19-Dec-14 12:14pm.
|
|
|
|
|
Sometimes documentation (and programs) takes on a life of its own. I keep running across snippets of code and documentation I wrote forty-plus years ago.
|
|
|
|
|
As many of you know I'm passing CP through a fine comb to find spam.
After days spent searching, pointing them to the forum, reporting spam and spammer and soliciting cooperation in kicking them I began to ask myself: "self, why do this people post in their personal forums all this spam, normally the same, under a ton of accounts? What do they gain of this?".
A quick search on st. Google brought me this articl, that points to a research of the profitability of spam. For those interested, here is the linkity[^] to the article.
EDIT: found one more here clickity[^]
Enjoy!
Geek code v 3.12
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- r++>+++ y+++*
Weapons extension: ma- k++ F+2 X
|
|
|
|
|
That simply goes for most advertising.
Bastard Programmer from Hell 
If you can't read my code, try converting it here[^]
|
|
|
|
|
I thought as much, but spam is actually negative, it is noise - it should give the opposite result, other than a sense of scam. I would never buy anything from such fishy figures, and I didn't think it could be so much profitable. I understand phishing - scams always work, and some phishing is actually well made. But spam... I never thought it could be so much profitable!
Geek code v 3.12
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- r++>+++ y+++*
Weapons extension: ma- k++ F+2 X
|
|
|
|
|
How is advertisment not negative noise?
Bastard Programmer from Hell
If you can't read my code, try converting it here[^]
|
|
|
|
|
I agree but advertisement is an agreement from the supplier of a service to the user - basically using the service you accept the existance of advertisement.
Spam is an advertisement disguised as a pertinent information in a stream of informations, it is plain noise in the sense that it disturbs an otherwise functional communication. Like Jeovah Witnesses that ring the doorbell on unday morning, or the ones that stops people in the streets.
While I may not have anything against advertisement posters in the streets I will surely be annoyed by someone interrupting my flow of actions with commercials, especially foul-smelling as the typical spam.
Geek code v 3.12
GCS d--- s-/++ a- C++++ U+++ P- L- E-- W++ N++ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t++ 5? X R++ tv-- b+ DI+++ D++ G e++>+++ h--- r++>+++ y+++*
Weapons extension: ma- k++ F+2 X
|
|
|
|
|
den2k88 wrote: ...be annoyed by someone interrupting my flow of actions with commercials,
Have you seen On-demand? It used to be that it acted like a dvd, hit a commercial, hit the fast forward button. A 2 minute commercial lasted 10 seconds. Now it seems the 2 minute commercial takes 4 minutes.
|
|
|
|
|
$65 million a year 
By the way have you tried this amazing product that enlarges your... Brain capacity? (well, that's where our brain is located according to women, anyway) 
My blog[ ^]
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|
|
Sander Rossel wrote: By the way have you tried this amazing product that enlarges your... Brain capacity?
Does it enlarge the Bacon Lobe?
New version: WinHeist Version 2.1.0
There's a fine line between crazy and free spirited and it's usually a prescription.
I'm currently unsupervised, I know it freaks me out too but the possibilities are endless.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
