Do you have this experience?
-
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
DavidCrow wrote:
What about those that write comments, and then go back and add code?!
Aye, now there's something you don't see too often, I imagine! On the occasions that I've done that, it works really well. Hmmm! 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
Oh yes.... for me that is an on-going process though. Management's rush to unrealistic arbitrary deadlines is a killer most of the time. Why is common sense not common? Never argue with an idiot. They will drag you down to their level where they are an expert.
-
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
Yup, this happens to mee to. But it's just because that when you write the code the first time, you have the big picture in your head to follow and implementation logic to think about, so the parameters validation and exception handling (in some cases) just slips your mind. Funny thing is I have always written the code, and after it was finished I started to comment it, and improve it like you said with parameter validation, exception handling, etc. But now I started to comment my code while writting it. Anyhow, because I am aware of what my commenting task was, I double check the code and while I'm at it ... the comments.:-> regards, Mircea Many people spend their life going to sleep when they’re not sleepy and waking up while they still are.
-
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
Refactoring is a way to clarify the code, same as documenting it, so I think it's natural to do them together that way. If I'm short on time, I'll even document thoughts for future refactoring inside the code. :rolleyes: 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
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.
-
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
Yeah, and triply so when you are also publishing a developers API, it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code. I.E. I have a property I set in a Client object, the property has all the business rules setup for a Name field so rather than rewrite it I just copy it to another object and the comments come with it so in the developers documentation it says for a Unit object "Client Name". I can't go through code and resist the urge to clean it up. Particularly code written in the heat of battle just before a deadline. I'm sure an artist looks at work they did in the paste and has to fight the urge to grab a brush and add a little bit here or fix something. How often do we ever get the time to do it though, it's sad really, you just can't have perfection. Or maybe that's Zen. ;)
-
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 do that all the time. When I have a complex method I work it all out as pseudo code comments and documentation comments line by line then go back in and write the code to fulfil it. It's a good thing to do for anything complex because it makes you think about it clearly first.
-
Yeah, and triply so when you are also publishing a developers API, it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code. I.E. I have a property I set in a Client object, the property has all the business rules setup for a Name field so rather than rewrite it I just copy it to another object and the comments come with it so in the developers documentation it says for a Unit object "Client Name". I can't go through code and resist the urge to clean it up. Particularly code written in the heat of battle just before a deadline. I'm sure an artist looks at work they did in the paste and has to fight the urge to grab a brush and add a little bit here or fix something. How often do we ever get the time to do it though, it's sad really, you just can't have perfection. Or maybe that's Zen. ;)
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 Wright -
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. 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)
-
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