|
Pretentious: Good code doesn't need documenting, it is self explanatory.
Reality: I am lazy
In practice, I try to minimize in-code documentation to reduce clutter and limit it to "magic" code, where I have used an unconventional technique that might confuse a lesser mortal.
Nothing succeeds like a budgie without teeth.
To err is human, to arr is pirate.
|
|
|
|
|
absolutely agree. Suffering with this right now.
Charlie Gilley
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
Has never been more appropriate.
|
|
|
|
|
I think it's more your "experience" knowledge that will be useful for the next person - so I would argue that a document explaining the domain knowledge and why certain APIs and code work they way they do may be of far more use than code documentation.
I say this because I spend a lot of time reading code and the most useful information I get from other developers is information like "yeah, this is what can go wrong and this is how the customer uses the API".
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
|
|
|
|
|
You asked for advice and are getting a whole range from a diverse set of viewpoints!
I will say that some of the most important things to document are:
1) Dependencies/Build/install/setup
2) Validation. How do you test/validate (or who else is responsible). Built in Testing?
3) Deployment Guidelines
4) Risks, Previous issues, and the most problematic code
5) The overall architecture, and a "Metaphor" for how to view the system
6) Any indication of how they might locate something (or the logic of the structure choosen)
Look at it this way. Assume YOU were walking in on day 1. The new developer to replace the previous.
You have NO CLUE what this system does. How to build it or test it. If you are even using the latest source.
Your confidence is in the toilet, and they need you to get up to speed.
What type of information would increase your confidence, and get you able to BUILD and VALIDATE the build the quickest?
Then what information would allow you to NAVIGATE the code logically?
Finally, assuming you only fixed a Typo... On your first day. What would make you feel okay to publish that change???
Document those things. NOT the code, per se.
IMHO
|
|
|
|
|
Sometimes the best coding dramas are written in the comments. (aside from some funny jokes)
But sometimes a good laugh is the best way to make people remember the oddities of certain hacks or unusual algorithms.
If I ever see Windows ME's source code, I'd expect to see shitfaced comments all over the people (evidence of Balmer's Peak)
|
|
|
|
|
Comments are often restricted to what the code does, this is only half the story. It arguably more useful to know why its been written or why it's been written a particular way, this can't always be inferred from the code itself.
|
|
|
|
|
Not sure if I brought up this topic before.
As I have aged, I am starting to develop Arthritis in my fingers, particularly my mouse clicking finger.
Does anybody know of a good speech to text program that can be used to control development in Visual Studio?
Are any of you suffering from the same issue?
Nutcracker Sweet
|
|
|
|
|
Slow Eddie wrote: Are any of you suffering from the same issue?
yes, I am.
I plan on going to the doctor and seeing what they can do for me, or if they have suggestions, such as alternative mouse devices, etc.
I have tried voice/speech programs, in the past, for other reasons than this topic, and it is not how I would want to code, etc.
|
|
|
|
|
|
@OriginalGriff uses trackballs, maybe he can help with suggestions for ergonomic mouse alternatives?
GCS/GE d--(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
|
|
|
|
|
Yeah I've been getting steadily worse in finger and knees, not overweight just a lot of wear and tear.
The less you need, the more you have.
Even a blind squirrel gets a nut...occasionally.
JaxCoder.com
|
|
|
|
|
Yes, I use trackballs, but they probably wouldn't help with the mouse click finger as that's the same on on mine.
Though I remember one Logitech trackie that used the thumb instead: Trackman Marble FX[^] - that might be worth looking at, since you can work both the ball and buttons with your thumb if you need to.
Personally, I didn't get on with it - too slow for Doom - but others swore by them.
I've yet to meet a TtS that worked well enough to be more help than harm, even for text documents - for dev? Try producing code on a tablet screen keyboard and you'll get the idea how bad it is.
There are eye tracking mice though - for example Precision Gaze Mouse[^] not sure how you click those though.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
OriginalGriff wrote: not sure how you click those though.
You have to cross your eyes to click! 
The difficult we do right away...
...the impossible takes slightly longer.
|
|
|
|
|
And extropic for a double click? 
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Thanks I will give both a try. I have tried all of the trackball mice, and the cursor moves much to slowly for me, even when I set the windows mouse parameters to full speed
ed
|
|
|
|
|
Have you tried glucosamine chondroitin?
|
|
|
|
|
My wife uses glucosamine and that has provided some relief and slowed down the deterioration. There is also some evidence to indicate the use of Turmeric to relieve the symptoms.
I had similar issues with my index (mouse clicking) finger. My solution was to re-train myself to use my second and third fingers to control the mouse. It took a couple of weeks, but now it's natural and my automatic way to use the mouse.
|
|
|
|
|
No but I am not far from it. 
ed
|
|
|
|
|
I have developed arthritis in both hands, and have now gotten dupuytrens contracture badly in both hands.
Slows typing and mouse work down considerably, and causes multiple keyboard key strokes in the the left hand
Thar's only two possibilities: Thar is life out there in the universe which is smarter than we are, or we're the most intelligent life in the universe. Either way, it's a mighty sobering thought. (Porkypine - via Walt Kelly)
|
|
|
|
|
I had surgery for dupuytrens 10 or 15 years ago. Followed by massive physio - an hour a day for 6 weeks or so, then twice a week for another 3 months.
Well worth it! My fingers are still nimble enough for the amount of typing and fine manual work I do, but I am often slowed down by a brain-finger disconnect that doesn't type what I intend. It started with transpositions like ...ino for ...ion, now does some quite off-the-wall substitutions.
Software rusts. Simon Stephenson, ca 1994. So does this signature. me, 2012
|
|
|
|
|
You seemed to indicate one particular "mouse finger". I think I use left click most. That said, it is possible to switch buttons on a mouse (configuration).
Now, a touch screen might also work: it should eliminate any number of mouse clicks (with screen taps, slides, drags)
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
|
|
|
|
|
Thanks. I forgot the switch thing. I will give it a try.
ed
|
|
|
|
|
Touch and click aren't always equivelant - there are (even MS) apps that just don't work well at all with a touch screen.
Which on a Microsoft App, on a Microsoft Surface, on a Microsoft OS is ... somewhat annoying ... 
Can never remember which apps though until I try to use them. Which annoys me even more! 
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
That's a design issue. My UWP apps are written with touch in mind; they run on tablets and desk tops. I prefer the tablet / touch experience in this case. Even created my own virtual keyboard that can be split, etc. and prefer it over the "built-in" one (for / in my apps).
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
|
|
|
|
|
Points to technical drawing instrument (7)
"It is easy to decipher extraterrestrial signals after deciphering Javascript and VB6 themselves.", ISanti[ ^]
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
