5 ms·

When coding from a well maintained specification, I always try to find an architecture where the structure of the code mimics the structure of the specfication.

When coding from a well maintained specification, I always try to find an architecture where the structure of the code mimics the structure of the specfication. This way, maintenance of the code becomes a lot easier. Sometimes, there are some small points in specification that makes it difficult to have the same structure in code. It is a "spec smell". Often, after discussion with spec writer, it was an incorrect point that had to be fixed in spec.

sametmax 8y ago
If I actually match a tech spec or a law, I usually put references to the related text in comments, next to the code handling it. E.G: I'll put the spec version + page, or law paragraph number. This way you know when you come back to it, what must stay, what must go, and what must change.
- riskable 8y ago
  Forget the cleverness of the code... If I see comments like that (providing direct references to the spec/law) I will know I am reading the work of a true artisan! Hats off to you, you wonderful person!
pjc50 8y ago
The most extreme version of this was a colleague who wrote a parser for the "human readable" version of the H265 spec. This could then be turned into executable code - and also a set of test streams. This resulted in him filing a large number of minor bugs between the spec and the reference implementation: https://hevc.hhi.fraunhofer.de/trac/hevc/query?status=accepted&status=assigned&status=closed&status=new&status=reopened&reporter=peterderivaz&order=priority https://hevc.hhi.fraunhofer.de/trac/hevc/query?status=accept... And a product: http://www.argondesign.com/products/argon-streams-hevc/ http://www.argondesign.com/products/argon-streams-hevc/ (page includes explanatory video)
- c0l0 8y ago
  Wow, that is some truly impressive piece of technology! Kudos to those who successfully completed the daunting task of actually implementing this pretty crazy idea.
  - pjc50 8y ago
    It was largely the work of one very smart person; not so much a 10x programmer as a mathematician^10. Edit: the tool critical to the project was "Ometa": https://en.wikipedia.org/wiki/OMeta https://en.wikipedia.org/wiki/OMeta
- chriswarbo 8y ago
  Very cool :) On a much smaller scale, VPRI made part of their TCP stack by parsing ASCII diagrams of packet contents (e.g. see the STEPS reports at http://vpri.org/writings.php http://vpri.org/writings.php ) Edit: Ah, I see user nradov has already mentioned this in a sibling comment :)
nradov 8y ago
VPRI wrote an experimental TCP/IP stack which parsed the structure of the relevant IETF RFCs to generate code. http://www.vpri.org/pdf/tr2007008_steps.pdf http://www.vpri.org/pdf/tr2007008_steps.pdf (Appendix E).
kian 8y ago
Another similar route is to code it as an interpreter over a data structure that represents the rules - When stored in something like a database, it can then be hot-reloaded.

sametmax 8y ago

If I actually match a tech spec or a law, I usually put references to the related text in comments, next to the code handling it. E.G: I'll put the spec version + page, or law paragraph number. This way you know when you come back to it, what must stay, what must go, and what must change.

riskable 8y ago
Forget the cleverness of the code... If I see comments like that (providing direct references to the spec/law) I will know I am reading the work of a true artisan! Hats off to you, you wonderful person!

pjc50 8y ago

The most extreme version of this was a colleague who wrote a parser for the "human readable" version of the H265 spec. This could then be turned into executable code - and also a set of test streams. This resulted in him filing a large number of minor bugs between the spec and the reference implementation: https://hevc.hhi.fraunhofer.de/trac/hevc/query?status=accepted&status=assigned&status=closed&status=new&status=reopened&reporter=peterderivaz&order=priority https://hevc.hhi.fraunhofer.de/trac/hevc/query?status=accept... And a product: http://www.argondesign.com/products/argon-streams-hevc/ http://www.argondesign.com/products/argon-streams-hevc/ (page includes explanatory video)

c0l0 8y ago
Wow, that is some truly impressive piece of technology! Kudos to those who successfully completed the daunting task of actually implementing this pretty crazy idea.
- pjc50 8y ago
  It was largely the work of one very smart person; not so much a 10x programmer as a mathematician^10. Edit: the tool critical to the project was "Ometa": https://en.wikipedia.org/wiki/OMeta https://en.wikipedia.org/wiki/OMeta
chriswarbo 8y ago
Very cool :) On a much smaller scale, VPRI made part of their TCP stack by parsing ASCII diagrams of packet contents (e.g. see the STEPS reports at http://vpri.org/writings.php http://vpri.org/writings.php ) Edit: Ah, I see user nradov has already mentioned this in a sibling comment :)

nradov 8y ago

VPRI wrote an experimental TCP/IP stack which parsed the structure of the relevant IETF RFCs to generate code. http://www.vpri.org/pdf/tr2007008_steps.pdf http://www.vpri.org/pdf/tr2007008_steps.pdf (Appendix E).

kian 8y ago

Another similar route is to code it as an interpreter over a data structure that represents the rules - When stored in something like a database, it can then be hot-reloaded.