: Re: Good Examples of and Practices in Code Documentation I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents

@Ogunnowo420

Vote Up Vote Down

In test-driven development the emphasis is on writing tests that clarify what code should do, rather than extensive documentation. Future maintainers of the code can then ensure that the code continues to exhibit the behavior it should by virtue of the tests.

The way tests are named form a type of documentation of the proper behavior of the code. Here is an example from the Ruby world:

describe "REST interface" do
describe "create" do
context "with valid parameters"
it "should create an object in the database" do
# test logic goes here
end
it "should return HTTP 200" do
# test logic goes here
end
end

context "with invalid parameters" do
it "should not change the DB" do
# test logic here
end
it "should return HTTP 400" do
# test logic here"
end
end
end

The block names are chained together, so that you can read them in English and they make sense: REST interface create with valid parameters should create an object in the database.

(0)

Login to post a comment!