I'm looking for the name of the technique about how to make code look like a sentence.
Example:
In many Test-Frameworks, you can just program tests like this (pseudo code):
expect(myObject.someNumber).toBeGreaterThan(4).toBeLessThan(7).toBeNotNull();
How is this principle called? Is there a pattern for this? Thank you!
Answer was provided by user "Will" and is: https://en.wikipedia.org/wiki/Fluent_interface
What you are trying to achieve here it resembles some sort of Design by contract test pattern which it's not bad but if your end goal is to achieve live understandable documentation from your tests you should try some BDD which provides a natural language to define your test cases that it's menat to be understood by anyone.
Related
Is there any way to use documentary comments for test-cases defined using Boost.Test macros ? Can I use Doxygen-styled comments, will they be parsed correctly?
The answer is to make your test cases so simple, so obvious and so readable that any documentation you write is superfluous. See the section titled Test Case Maintenance and Design in my rewrite of the Boost.Test docs.
I have no idea how to build S-exp.
I want to do it, because I need to build AST for my langauge.
At the beginning I used RubyParser to parse it to sexp then code gen.
But it must be ruby's subset I think.I cant define the language what I want.
Now I need to implement parser for my language.
So anyone could recommend any ruby tool that building AST for S-expression ?
Thanks!
It is not very clear from your question what exactly do you need, but simple Google search gives some interesting links to check. Maybe after checking these links, if they are not the answer to your question, you can edit question and make it more precise and concrete.
http://thingsaaronmade.com/blog/writing-an-s-expression-parser-in-ruby.html
https://github.com/aarongough/sexpistol
You might try the sxp-ruby gem at http://github.com/bendiken/sxp-ruby. I use it for SPARQL S-Expressions (SSE) and similar methods for managing Abstract Syntax Trees in Ruby.
Maybe you could have a look at this gem named Astrapi.
This is just an experiment :
describe your language elements (concepts) in a "mm" file (abstract syntax)
run astrapi on this file
astrapi generates a parser that is able to fill up your AST, from your input source expressed in s-expression (concrete syntax of your concepts).
I have put a modest documentation here.
I'm running a refactoring code dojo for some coworkers who asked how refactoring and patterns go together, and I need a sample code base. Anyone know of a good starting point that isn't to horrible they can't make heads or tails of the code, but can rewrite their way to something useful?
I would actually suggesting refactoring some of your and your coworkers' code.
There are always places that an existing codebase can be refactored, and the familiarity with the existing code will help make it feel more like a useful thing and less like an exercise. Find something in your company's code to use as an example, if possible.
Here are some codes, both the original and the refactored version, so you can prepare your kata or simply compare the results once the refactoring is performed:
My books have both shorter examples and a longer, actually a book long example. Code is free to download.
VB Code Examples
C# Code Examples
A nice example from Refactoring Workbook
There are a lot of examples on the internet of simple games like Tic-Tac-Toe or Snake that have a lot of smells but are simple enough to start with refactoring.
The first chapter in Martin Fowler "Refactoring" is a good starting point to refactoring. I understood most of the concepts when one of my teachers at school used this example.
What is the general knowledge level of your coworkers?
Something basic as code duplication should be easy to wrap their heads around. Two pieces of (nearly) identical code that can be refactored into a reusable method, class, whatever. Using a (past) example from your own codebase would be good.
I would recommend you to develop a simple example project for a specific requirement.
Then you add one more requirement and make changes to the existing classes . You keep on doing this and show them how you are finding it difficult to make each change when the code is not designed properly. This will make them realize easily because, this is what those ppl will be doing in their day to day work. Make them realize that , if patterns and principles are not followed from beginning, how are they going to end up in mess at the end.
When they realize that,then you start from scratch or refactor the existing messed up code .Now add a requirement and make them realize that it is easy to make a change in the refactored code, so that you need to test only a few classes. One change would not affect others and so on.
You could use the computer ,keyboard and printer class as an example. Add requirements like, you will be wanting the computer to read from mouse , then one more requirement can be like your computer would want to save it in hard disk than printing. Finally your refactored code should be like, your computer class should depend on abstract input device class and output device class. And your keyboard class should inherit from Inputdevice class.
Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin considers refactoring.
I'm loving Refactoring Guru examples.
In there you can find design patterns examples too.
Refactoring is non-functional requirement when code perform correct functionality for which it is designed however difficult to debug, requires more effort to maintain and some performance bottleneck. Refactoring is to change to be easily maintainable, good readability and improve efficiency.
Thus we need to focus on criteria to make code more readable, easy to maintain.
Its obvious that having very large method/function might be difficult to understand.
Class depends on other hundreds of class make thing worst while debugging.
Code should be readable just like reading some workflow.
You can also use tools like sonar which can help you to identify critical criteria such as "Cyclomatic Complexity"
http://www.sonarsource.org/managing-cyclomatic-complexity-to-increase-maintainability/
You ask them to write code them self and check how tool does refactoring.
Apart from that, you can write code in eclipse and there is option available which does refactoring for you...
It's a bit dated (2003), but IBM has several refactoring examples (that work[ed?] in Eclipse) at http://www.ibm.com/developerworks/library/os-ecref/
Hai guys,
I ve seen people including comments in their program..
Is it to improve inter-programmer communication
and code readability, by explicitly specifying programmers’
intentions and assumptions?
Should comments be in technical terms rather than in natural launguage terms?
How to use comments as effective as possible?
Is it really a good practice adding comments to a program?
Comments should only be used to explain why the code is the way it is. It should never explain what the code is doing. What the code is doing is described by the code.
That being said, some languages have tools that look for special characters in the comments in order to generate documentation. Java is one such language. But these aren't so much code comments as they are documentation that happens to use the same syntax as language comments.
Comments can be used for auto-documentation, communication amongst other developers, memory, todo lists, or basic explanations of functionality. Note that comments ought to be supplementary - if your code needs comments, you need to reconsider your code.
To be as effective as possible, work out a template for your comments to exist in. Again, this will not only help you read and understand your code, but it may help a parser create documentation for you from your comments if they're in a consistent format throughout the code.
Writing clear code is always the first step to making your code easy to understand. You can then explain parts that are not clear by looking at the code, in comments.
For myself, comments explain what I was thinking at the time. That way, six months from now when I don't remember what I was writing, I can use the comments to understand.
Some classic uses of comments:
Explaining why code wasn't done in the most obvious way -- Such as interfacing with systems that use weird or old ways to talk.
Explaining what code might call this code -- Such as in large and complicated system. You can add examples showing code that might need to call this.
Documenting exceptions to current coding practice -- Such as legacy code that hasn't been refactored to use the current systems.
As a rule, if you ever find yourself doing something non-obvious, comment it.
An alternative way of commenting is to start by writing the body of a function as comments. Then break the comments apart and put the code underneath. When it finally works, cleanup and fix the comments.
Ciao!
I try and comment each function describing at a high level, but precise way, what the function does. The precision should be such that it is not necessary to read the body of the function to understand what the function does, or to re-implement it and have it work perfectly with any code that calls it.
Other than that, I try and keep functions small enough that the above is basically all the necessary documentation.
Once in a while, there may be something obscure or odd in what is being done in the code - I document that. Anything that isn't obvious or intuitively right, or that you spent some time thinking about, should be documented.
Just imagine you have a memory problem and will forget writing this program in a month. Then imagine you have to go back and fix it. What would you like commented and how could those comments be made most useful to you?
it's better to make the program self-describing, then no much comments are needed.
First try to write code so people can follow without comments.
I'm developping a mini search engine, and I want to implement the feature of searches based on logic operators AND OR...
I'm having a difficulty on parsing a query containing AND, OR, NOT... especially when it comes to parentheses... (cat or dog) not (bike not mike)
For simple AND, and OR queries, it's obviously too simple and I figured out how to formulate the sql query, but when it becomes that complicated I'm lost !!!
I'm not sure if search engines have this feature, but I want to dive into it for learning purpose.
I apologize for my last question which wasn't really clear, I hope this time I'm doing better.
I'd recommend looking at a lexer/parser generator like ANTLR. A simple grammar should be able to sort you out. There might even be an existing grammar for such a thing.
Take a look at the searchparser.py example from the pyparsing project.
It shows a way to implement:
AND,
OR,
NOT,
grouping and
wildcards.
All done in 293 lines of code (including comments and tests) ...
If you are using MySQL you can use the builtin boolean search:
http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html