Do you have this experience?
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
That sounds pretty familiar. If I'm in a particular area of the code, I tend to look around for any obvious gotchas in either the code or comments/documentation. If I find anything and fixing it appears to be low risk, I'll do so. Every so often I'll also go on a compiler/lint issue hunt and kill any potential nasties that have crept into the project recently too. Anna :rose: Currently working mostly on: Visual Lint :cool: Anna's Place | Tears and Laughter "Be yourself - not what others think you should be" - Marcia Graesch "Anna's just a sexy-looking lesbian tart" - A friend, trying to wind me up. It didn't work.
-
John Cardinal wrote:
it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code
Man, I hate this when I'm maintaining older code. I've seen some comments that have nothing at all to do with product, someone stripped the code from another product we sell, and left the comments as they were. It's great to finally read through a procedure (assembly) you thought had nothing to do with what you were looking for, only to realize the comments were completely bogus. X| The 8 Character limit on variable names doesn't help either, but that's another issue. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright8 Character? WTF? I created this variable just yesterday:
private Guid _MostLikelyRateUnitChargeDescriptionID=Guid.Empty;What could be more important than nice fat variable names that mean what they represent? It's the lowest common denominator in the world of understandable code. -
Funny, that's how I was essentially brought up writing software. Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan. Cheers, Drew.
Drew Stainton wrote:
Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs.
Same here, only it was in 1989. We were not even allowed in the lab until several weeks later, just to ensure we were not writing code. As a matter of fact, all of my undergraduate CS courses required a requirements/specifications document to be handed in along with the code itself.
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
-
8 Character? WTF? I created this variable just yesterday:
private Guid _MostLikelyRateUnitChargeDescriptionID=Guid.Empty;What could be more important than nice fat variable names that mean what they represent? It's the lowest common denominator in the world of understandable code.We are still coding in a modified version of Series/1 assembler from back in the 80's. Don't ask me why, but we do. It blows. We also have C+ and VB apps, but it's not all migrating to something modern yet. :sigh:
John Cardinal wrote:
What could be more important than nice fat variable names that mean what they represent?
I appreciate that everytime I load up VS. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright -
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
I'll do that for anything i have to stop and think about - anything non-trivial in its logic, really. Now, whether i leave the comments in once i'm done coding or not... ;P
---- Scripts i've known... CPhog 0.9.9 - make CP better. Forum Bookmark 0.2.5 - bookmark forum posts on Pensieve Print forum 0.1.1 - printer-friendly forums
-
Drew Stainton wrote:
Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan.
I think this is the goal of any software product, but it also requires that the design goals do not change/evolve during the process. I have seen government projects try this, you spend a year planning and producing a ton (often litterally) of documentation on what you will do, and then spend the next 6 months editing it for the changes over the last year, then the next 3months editing it for the changes over the last 6 months... etc.... by the time you actually start developing to the documentation, you still have to take quarterly stops to rewrite code and update documentation. Or you stick to the documentation and make a product that will never be used. This obviously is not the case for all projects. I do believe there are projects that are best in the design&document first strategy, and there are those that require agile development. The first and hardest decision is figuring out which is which. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
Jeffry J. Brickley wrote:
but it also requires that the design goals do not change/evolve during the process
Definitely. Although in my experience (12 years working for a government) I only ever saw two analysts profide feature spec. docs for signing off. The feature creep and spec. changes were more due to the analysts getting all excited "oh, ya, we can do that - no problem. Oh, oh and we can do this too..." and providing the fodder for the spec changes. Ultimately a good portion of the projects never got finished. It's always a balancing act, but a little backbone goes a long way ("sure we can change/add that - in version 2"). Of course it's not a perfect world and there will always be some places where a little agility is required. There are things that can be done to minimize that though. Cheers, Drew.
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
When including the effort to document in an interface in my planning, I tend to write easier-to-document interfaces (which I think highly correlates with "easier to use") Yeah, when documenting stuff, there's so much poppign up that could be made easier.
Some of us walk the memory lane, others plummet into a rabbit hole
Tree in C# || Fold With Us! || sighist -
Jeffry J. Brickley wrote:
but it also requires that the design goals do not change/evolve during the process
Definitely. Although in my experience (12 years working for a government) I only ever saw two analysts profide feature spec. docs for signing off. The feature creep and spec. changes were more due to the analysts getting all excited "oh, ya, we can do that - no problem. Oh, oh and we can do this too..." and providing the fodder for the spec changes. Ultimately a good portion of the projects never got finished. It's always a balancing act, but a little backbone goes a long way ("sure we can change/add that - in version 2"). Of course it's not a perfect world and there will always be some places where a little agility is required. There are things that can be done to minimize that though. Cheers, Drew.
Drew Stainton wrote:
changes were more due to the analysts getting all excited "oh, ya, we can do that - no problem. Oh, oh and we can do this too..." and providing the fodder for the spec changes. Ultimately a good portion of the projects never got finished.
There is always a little of that. I have been accused by some of doing the same by another group locally. I tend to take what the customer asks for and do it. If he requires xx for a test in 3 months, I do it, even if it violates the original idea of the project. Once upon a time I only displayed data. Now I process it, predict it, trace it, reproject it, compare it and simulate it. All because customer needs have changed.
Drew Stainton wrote:
Of course it's not a perfect world and there will always be some places where a little agility is required. There are things that can be done to minimize that though.
I have never found a way to stop that in my biz, or even slow it down. The inputs change, the analysis changes. The only thing that doesn't change is the math core. but even that changes to some extent as I extend physics engines into multi-core architectures, add parallel analysis of data we never tracked before, and take into account changes in display engine capability as graphics cards are changing in capability. It's a constant state of flux, you reign it into multiple releases a year, but adaptive methods are the only thing I found that works. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Paul Watson wrote:
It seems to happen less now that I write test first.
That's a good point, and I would agree, I find I refactor less. One thing I still can't do is truly write the test first. I have to still implement at least a stub class because I think in terms of the "package", and that means coming up with the class name and at least an initial pass at the internal fields, public properites (C# centric) and method names. And at least that way, I can use Intellisense when writing the tests. How about you? Marc Pensieve
I try to be practical, not everything test first, while not forgetting that test first does catch silly mistakes in repetitive code. It is hard to define really and I am still refining the balance as I learn. I am not one extreme or the other though. regards, Paul Watson Ireland Feed Henry! K(arl) wrote: oh, and BTW, CHRISTIAN ISN'T A PARADOX, HE IS A TASMANIAN!
adapted from toxcct:
while (!enough)
sprintf 0 || 1
do -
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
All of the above, for sure. Especially when commenting code that has NO comments written by MUSH less experienced developers, who think every variable has to be i, j, k, or l. Were they FORTRAN programmers in a previous life or what :mad: I have to rename stuff just so I can keep track of what it is doing so I can add a resonable comment or produce documentation. People that start writing code immediately are programmers (or hackers), people that ask questions first are Software Engineers - Graham Shanks
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
I write a comment in the code that I need to comment the code ... not because I have to (which I do) but because I should. But then by the time I'm done writing that piece, I feel less productive with the comments -- so I tend to procrasinate, and eventually my boss reminds me of it! So I eventaully do end up writing the comment -- just need the right motivation. :laugh: - Malhar
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Marc Clifton wrote:
document my code
i never document or comment my code. i write code the is self-documenting.
-
Marc Clifton wrote:
document my code
i never document or comment my code. i write code the is self-documenting.
ahz wrote:
i write code the is self-documenting.
In my experience, that only goes so far. A well placed, valid comment can do wonders to help maintaining code, especially if someone new to the project or less experienced is working on it, or for yourself if it's a code you haven't looked at it in a year or two. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright -
Marc Clifton wrote:
document my code
i never document or comment my code. i write code the is self-documenting.
ahz wrote:
i never document or comment my code.
Well, in particular, I'm refering to xml comments around classes, properties, methods for auto-generating help documentation. Marc Pensieve
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Certainly. I'll document a lot while desigining and writing the bulk of the code too, but there are those times where I lose patience with my own process and just need to see something work right now! Especially in those cases, taking the extra step to go through to document the code often leads to refactoring for a better overall design.
-
ahz wrote:
i write code the is self-documenting.
In my experience, that only goes so far. A well placed, valid comment can do wonders to help maintaining code, especially if someone new to the project or less experienced is working on it, or for yourself if it's a code you haven't looked at it in a year or two. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven WrightI couldn't agree more. For me, it's usually deciphering my intent in my own code a year later; I help myself alot to maintain and update code with those comments. I generally write clean code (from a "self-documenting" standpoint), but I agree - that only goes so far.
-
Drew Stainton wrote:
Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan.
I think this is the goal of any software product, but it also requires that the design goals do not change/evolve during the process. I have seen government projects try this, you spend a year planning and producing a ton (often litterally) of documentation on what you will do, and then spend the next 6 months editing it for the changes over the last year, then the next 3months editing it for the changes over the last 6 months... etc.... by the time you actually start developing to the documentation, you still have to take quarterly stops to rewrite code and update documentation. Or you stick to the documentation and make a product that will never be used. This obviously is not the case for all projects. I do believe there are projects that are best in the design&document first strategy, and there are those that require agile development. The first and hardest decision is figuring out which is which. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
ahz wrote:
i never document or comment my code.
Well, in particular, I'm refering to xml comments around classes, properties, methods for auto-generating help documentation. Marc Pensieve
Marc Clifton wrote:
xml comments
**bleagh** **blehch** **barf**