Dumb questions about coding...

[Karim]

Not specifics, just about the process.

If you're developing something small, let's say ~1000 lines, how many of you jump straight to coding? Is this even recommended? How much time is spent on design documents/pseudocode/algorithm design? I guess I'm wondering if there's any way to speed up the process.

Also, how much reference material do you use when you're coding? I always seem to have to refer back to various bibles and am wondering if that's fairly standard or if some of this stuff should have been committed to memory.

And when/if you get stuck implementing something, what do you do? Do you go back and rethink the design document, get someone else to look at your code (not always possible), scour books, or something else?

[Radii]

If you're developing something small, let's say ~1000 lines, how many of you jump straight to coding? Is this even recommended? How much time is spent on design documents/pseudocode/algorithm design? I guess I'm wondering if there's any way to speed up the process.

i think a lot of this depends on how comfortable you are with the language you're coding in and what you're doing. I'll write up a real small flow diagram and make notes on what methods/functions I think I'll need. Then the first thing I do when I start the project/set up the source file is stub out all the fuctions I know I'm going to need.


Also, how much reference material do you use when you're coding? I always seem to have to refer back to various bibles and am wondering if that's fairly standard or if some of this stuff should have been committed to memory.



man pages/* in a nutshell books are my friend. At my current job I'm a Java monkey, so I have my Java in a Nutshell book on me at all times. I'm self taught in any/every language I know so there may be functions that I don't know about or that I haven'tused often and so whenever I'm doing something even remotely new I search the web to see if there's any code I can borrow/start from, and between online help and my good friend O'Reilly, I can figure out pretty much anything I need to.

It seems to me that with new visual languages, the goal is to not to have to commit anything to memory at all. In C I *kneW* my stuff b/c I was coding in a vi window, I didn't have any assistance, I had to have shit memorized or look it up. In my pretty little JBuilder interface, when I enter a '.' it automagically brings up every function/variable underneath the object I'm using. Makes for less memorization/more reliance on outside tools, which isn't a terrible thing IMO.


And when/if you get stuck implementing something, what do you do? Do you go back and rethink the design document, get someone else to look at your code (not always possible), scour books, or something else?

I e-mail some of my tech friends that are much smarter than me... that's very situation dependant. I like having a collaberative work environment so I can ask for help. Honestly though, the first thing I do any time I'm stuck is I look for examples, or look to see what other people have done to give me ideas. Then i'll start looking to friends/coworkers for advice.

[Cap Ologist]

Also, how much reference material do you use when you're coding? I always seem to have to refer back to various bibles and am wondering if that's fairly standard or if some of this stuff should have been committed to memory.?
I use "Sam's Teach Yourself in 21 days" as a base reference guide, I have several sites bookmarked that I use for ideas and information.


And when/if you get stuck implementing something, what do you do? Do you go back and rethink the design document, get someone else to look at your code (not always possible), scour books, or something else?
When I get stuck, I email a friend of mine who has more experience than I do to ask for suggestions on design/implementation. If I get bogged down trying to figure out how to code something, I'll post here and hope that I haven't annoyed all the people who've helped me in the past.:p

[MacroGuru]

Not specifics, just about the process.

If you're developing something small, let's say ~1000 lines, how many of you jump straight to coding? Is this even recommended? How much time is spent on design documents/pseudocode/algorithm design? I guess I'm wondering if there's any way to speed up the process.

Also, how much reference material do you use when you're coding? I always seem to have to refer back to various bibles and am wondering if that's fairly standard or if some of this stuff should have been committed to memory.

And when/if you get stuck implementing something, what do you do? Do you go back and rethink the design document, get someone else to look at your code (not always possible), scour books, or something else?
Personally, 1000 Lines or less, I do the bulk of the documenting inside the code. However at work, we are in the process of going through a Sarbanes Oxley audit, and I am in the process of typing up an SDLC, project plan, and business process flows in order to justify and verify what we do, this is also setting up future development rules and procedures which outlines what you just stated, regardless of the line size.

[CAsterling]

Not specifics, just about the process.

If you're developing something small, let's say ~1000 lines, how many of you jump straight to coding? Is this even recommended? How much time is spent on design documents/pseudocode/algorithm design? I guess I'm wondering if there's any way to speed up the process.

For something approx 1000 lines or so, I would say do some design first - think of what the end result is meant to be and put down some basic ideas of how to get there on paper - otherwise you might get part way through and forget why a certain subroutine was needed.
I wouldn't do a detailed design spec, flowcharts or process documentation for something that size unless it was one part of a much bigger project.

As for reference material, the ability to RTFM is one of the most underrated skills of all programmers - very few know everything, so having good reference doc handy is crucial. Friends are helpful, but remember even supposed experts can and do give bad advice because they don't have your total understanding of what you are attempting to achieve.

The problem with this type of advice is that it depends heavily on circumstances, if you are doing a degree project then do all the doc as educators love to see it (I always did it after the code, but heck I was a rebel).
If you are doing it at work, then what we mainly do is find something that already exists (even if it means calling a few freinds from other companies), adapt/expand on it and copy/alter any existing design doc to meet your needs afterwards - its rare to write something from scratch.
If you are doing it for yourself as a one man project then minimal doc is the way to go just enough so you know what and why you did it when you come back to it in 12 months.

Personally I tend to code first and doc later (if ever), but I've been coding for 20 years - it also helps that I move jobs frequently so I normally get out before I forget why I did something a certain way :D

[Karim]

Thanks guys. This really helps.

[Yossarian]

A quick quote I like with regard to documentation.

When you write a piece of code, two people understand it. You - and God.
Six months later, only one person understands it.

[hoosierdude]

Personally, 1000 Lines or less, I do the bulk of the documenting inside the code. However at work, we are in the process of going through a Sarbanes Oxley audit, and I am in the process of typing up an SDLC, project plan, and business process flows in order to justify and verify what we do, this is also setting up future development rules and procedures which outlines what you just stated, regardless of the line size.


Do you find that your ingame documentation is needed? What about protection of your intellectual property?

I find that a lot of docs to myself inside the code can confuse at times. What do you do to keep it clear and concise but remind you why it was there in the first place?

[Radii]

Do you find that your ingame documentation is needed? What about protection of your intellectual property?

I find that a lot of docs to myself inside the code can confuse at times. What do you do to keep it clear and concise but remind you why it was there in the first place?


Keeping your code short is overrated IMO. Many programmers and geeks seem to love using the most convoluted, unreadable(BUT IT ONLY TAKES 14 CHARACTERS ON ONE LINE INSTEAD OF THREE LINES AND FIFT?Y CHARACTERS OF INSTRUCTIONS OMG) code imaginable. Keep it simple, stupid. This is the biggest thing I do to help document my code. I make liberal use of whitespace and if something is easier to read on 2 lines instead of crammed together in something complex, I space it out.

I write comments for each method I write no matter how simple. Often my work and methods and changes are because of a customer request. I note the date/reason/functionality behind the function. Any line of code or any little block of code within a function that isn't as simple as x++; gets a 1 or 2 word comment describing what it does if necessary.

Once you're used to commenting a lot it really becomes old hat to comment extremely thoroughly and concisely within the code.

[Draft Dodger]

A quick quote I like with regard to documentation.

When you write a piece of code, two people understand it. You - and God.
Six months later, only one person understands it.

so true.

[hoosierdude]

I agree that short code is overrated. But bloated code is a problem as well. I try to keep it how you say... clean, but enough to do my job without adding in too much that isn't.

It is a tough, fine line I am finding out between too much and too little sometimes. Of course that could be my inexperience as well.

[MacroGuru]

Do you find that your ingame documentation is needed? What about protection of your intellectual property?

I find that a lot of docs to myself inside the code can confuse at times. What do you do to keep it clear and concise but remind you why it was there in the first place?
Providing external detailed documentation always help, I am in the process of tearing the game apart right now as far as coding goes and writing the documentation on class objects and various other aspects as the lead developer on the project (Believe it or not it isn't me) did not comment his code a lot.

As I am moving forward learning new things with how Sarbanes Oxley wants everything done, I am seeing some cleaner ways to code, and work changes into the code and documenting them there.

Internally, from what I have picked up from my dad and his old school days of coding was to list all documentation in the code that you can, referencing them by a comment on the line you are dealing with, that way, if I see a specific doc # in the initial header file, I just do a find on the number, and it takes me to where I need to read about it in the code, or look at the code. This mainly works for change controls, but is definately ok with smaller programs.