Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

When creating a new file format for an application, you can write the code or the documentation first.

When writing the documentation first, you have a better idea of what you should implement.

However, you might need to change a lot of the documentation you have written afterwards when writing the code, because you may discover certain things aren't very efficient to implement that way.

So: When creating a new file format, what should you write first: The code or the documentation?

share|improve this question
    
Make your code the documentation. Then there is no debate. :-) But more seriously, this is not one size fits all. Sometimes one is better than the other, but which one depends on specific circumstances. –  btilly Jul 9 '13 at 8:43
    
I find that writing tests (unit and integration) makes sure that your code has a nice and understandable API first, and can act as source for examples and explanations. And when I choose open source libraries, I always prioritise ones with tests. –  nirth Jul 9 '13 at 8:44
1  
@btilly Code should be documented indeed, but for file formats there should be a seperate documentation too, because that makes it much easier for other developers to implement your file format. –  Jop Vernooij Jul 9 '13 at 8:46
    
@Jop In my life I've created a lot of micro file formats for configuration where it really made more sense just to code it. Any programmer looking at it will say, "Oh, I just add this field to the config, then look for it over there in my code and I'm done." The configuration evolves from there with the only requirement being that you should leave comments in your config and use clear field names. But if you expect others to reimplement your file format, then absolutely, you want documentation. –  btilly Jul 9 '13 at 16:47
    
@btilly Yes, I expect/hope others to implement it, too. That's what I meant. –  Jop Vernooij Jul 9 '13 at 17:13

3 Answers 3

up vote 16 down vote accepted

You are confusing documentation with specification.

Specification is the process (usually collaborative) through which the definition of what the format should do and how a hypothetical application should handle it, render it, or parse it.

It's a design process like the one W3C does when creating the HTML or CSS specifications way before browsers implement it.

Or course the product of this process can be understood as "documentation", but it's not the documentation of an application.

If you are creating a new file format, discuss and design the specification.

Then code the application that uses that file format ( or have others code it ).

But to create a new file format you don't have to write a single line of code. The specification may never be implemented, yet it exists as an specification.

Obviously when an specification does get implemented, it is revised and extended with the feedback of implementers.

share|improve this answer
1  
Writing a complete specification before the implementation is what you'd do in the waterfall model. Nowadays, successful specifications like HTML5 are evolved alongside with the implementation. –  oberlies Jul 9 '13 at 11:00
    
... and one good reason for that is that it helps discover issues (unnecessary complexity, security issues, missing features, etc.) before the spec is finalized. –  delnan Jul 9 '13 at 11:09
1  
@oberlies It's obvious that once an specification is implemented, it will not be frozen. Regardind the waterfall thing: I'm not talking about analysing and designing a whole app in advance (cascade). What I'm talking about is creating the speficication of a file format. It's not the same. –  user61852 Jul 9 '13 at 11:11
    
@delnan It's obvious that once a specification is implemented by someone, it's not gonna be frozen in time. The need to improve the specification arises and so on. But an initial specifition must be done. –  user61852 Jul 9 '13 at 11:14
    
Must? As in, nothing else is gonna work? I highly doubt that, developing spec and implementation from very early on seems to work just fine. Unless by "initial specification" you mean "a rough idea in the implementer's head". –  delnan Jul 9 '13 at 11:22

The documentation that should come first is the one that specifies what the format must accomplish. If the user should be able to specify text size, color, links, and have them reproduced, all of this information needs to come first. This is distinct from documenting how it was implemented. As you said, this kind of technical doc is hard to write completely in advance, since you cannot foresee all consequences of decisions you make early on. My experience is that it is best to interleave both tasks and finish the technical documentation simultaneously with the reference implementation and test suite.

share|improve this answer

This is really a question of development process and development methodology. Any approach can be equally valid, but some may work better in your organization than others.

I'm a fan of agile processes, and I'm not a big fan of comprehensive documentation. Documentation has a tendency to cost more to write than the benefit you get from people reading it (which they tend not to do), and it has a tendency to become outdated quicker than it can be written.

Instead I would write executable specifications using specification by example. Various tools support this, e.g. FIT or Cucumber. Then you start by writing a little bit of specification, and then write just enough code to satisfythis specification. Then a little more specification, etc.

In the end, you get a living documentation, that can be verified to always reflect what the system actually does.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.