Categories
Tutorials & Tips

Plain text markup languages

Instead of relying in complicated bloated office programs or embedding messy WYSIWYG interfaces in web applications, a quick way to format plain text is to use a markup language. Just like HTML that has tags to structure a document and render into special formatting, plain text can also be “pretty” by using a standard markup language. It is easier to type as they normally don’t interfere much in the visual aspect of the text. That means that even if you don’t have support for the markup language, you can read the text without problems.

On code documentation files, plain text markup languages are preferred over languages like HTML or LaTeX to waste little time on editing without loosing good presentation.

Some of these languages are:

Markdown

It was created as a plain text to HTML markup language made to simplify writing formatted text that will generally end translated to HTML tags. The syntax is very simple and supported on many text editors and web platforms.

Basic markup guide

# Heading 1
## Heading 2
*Bold*
– List item 1
– List item 2
+ sublist item
[text](Link)

Cheatsheet

You can find a markup cheatsheet here

You can read more on the markdown project website.

Asciidoc

As the website defines it, it is more than just a markup language. It is a text based document generation tool. You can create beautiful documentation with it by exporting to formats like HTML, PDF or LaTeX. Besides the usual markup of plain text, you can also use variables with a certain value to reuse across your document, saving you from typing repeated text or update a value in several places with one change.

Basic markup guide

== Heading 1
=== Heading 2
\*Bold\*
* List item 1
* List item 2
** sublist item
link_url[Link_text]

Cheatsheet

There’s an asciidoc cheatsheet here

You can read more at the asciidoc website.

Org

Org was born in the Emacs org-mode users world. I think besides Emacs there are no other places where org syntax is being used. Org lets you do many things in plain text, like organizing your to-do lists, your agenda, plan your projects, add source code blocks and execute the code right in your document among many other things. You can easily export to HTML, LaTeX, PDF among other formats. Some parts of the syntax can be complicated but since it is intended to be used within Emacs, it’s easy to handle with simple keyboard shortcuts.

Basic markup

* Heading 1
** Heading 2
\*Bold\*
/italic/
\_underline\_
- List item 1
- List item 2
  - Sublist item
[[Link_url][link_text]]

Cheatsheet

There are many Org-mode key stroke cheatsheets, but for markup only you can consult here

You can read more on the org-mode website.

Keyboard photo by Wouter Verhelst on Flickr
Categories
GNU/Linux Free Software & Open Source Programming & Web Development

10 PHP code quality tools to avoid a mess in your projects

img_2052

When programming in any language there are certain common errors that everyone makes as they mature and evolve their programming skills. In the case of PHP, I’ve seen a lot of ugly and complicated code around, since the language is very permissive.

To have a good and healthy PHP code base so it won’t resemble the unmanageable cabling mess in the picture above, your project needs to have the following:

– no spaghetti code
– code reuse (avoid code repetition)
– avoid complicated nested loops
– Encapsulation (organize code in classes)
– Clean user I/O
– Code Documentation
– Consistent code conventions
– Tests

Luckily there are some PHP code quality tools that can help us address most of these problems and give us a diagnostic of our project’s code health.

###Documenting your code

PHP Documentor: Documenting code with PHP Documentor is very simple and easy. You just need to follow a very simple markup before your functions and classes and the tool will generate all the developer documentation for you. It’s also very handy when adding new people to your project or inheriting someone else’s work. Just by seeing the documentation comments in the code you can understand what a given function does, what each of its parameters need to be and what it returns. You can also expand the documentation to add use cases and even unit tests!

###Code consistency

PHP Code Sniffer: A tool that analyses the syntax of your project’s code based on a PHP syntax standard. Known standards like PEAR or Zend syntax styles are included by default but you can also customize and define our own team’s style.

PHP Depend
Analyzes the code for common issues and potential optimizations. Some examples of those are:

– if your function is too long
– if your function has too many parameters
– variable names too long or too short
– too many nested cycles
– use of eval()
– name convention consistency
– unused methods or variables

PHP Mess detector: A fork of PHPDepend with a friendlier UI and configuration options

PHPCPD (Copy/Paste Detector): A tool that will detect copy/pasted code across your project that can be reused.

###Testing

Unit testing

PHP Unit and Simpletest: Unit testing has been very useful in my experience on recent projects where I’ve been allowed to implement it. On personal project I always tend to do unit testing before layout out all my code. It might take more time to develop your project at the beginning but it will save you tons of time debugging and tracing back errors when you think you’re done programming.

If you’re using Ubuntu and have problems running PHPUnit, here’s a post about how to solve the problem.

Here’s a quick guide on how to start using Simpletest.

Integration Testing (browser emulation)

Mink and Behat are the tools you’ll need to do browser emulation to test your interfaces and how it’s all put together and interacting for the user.

###Put it all together with Phing

Phing is a tool like GNU Make or Apache Ant but it’s in PHP and extensible via PHP classes. You can put all of these tools together with Phing, so you can automate all the checking, testing and even deployment and cleanup of files or databases.

With these tools you can have a very robust quality assurance workflow on your project. Of course, this doesn’t mean that there’s not going to be any bugs or that your project will have the best code, but at least it will reduce very common problems, will increase code maintainability and help you spot problems easier. The transitions from adding or removing people from the project (like in large teams or dynamic organizations) will be smoother, as well. Also those transitions will be even smoother if you consider using an established web framework for your project instead of writing your own.

I gave a talk at FSL Vallarta 2012 about this, you can download the slides for the talk “Herramientas de calidad en codigo PHP” here. (slides in Spanish)