From 8da3adcd30f039fe8a96af3eb10ec7cb5d289cf0 Mon Sep 17 00:00:00 2001 From: Chris Meunier Date: Thu, 11 Jan 2018 16:48:41 -0800 Subject: [PATCH] Update README.md (#2) Minor updates --- README.md | 75 +++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 37 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 14792a8..c9a2d44 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,69 @@ # MASM Styleguide and Resource List The Microsoft Assembler (MASM) is a popular assembler for Windows platforms. Unsurprisingly, there has been very few -notable projects in MASM in the last decade. Small, fast code just isn't as important as it used to be. Still, it is -a very interesting exercise to learn MASM and use it. It's difficult to get binary sizes smaller than you can with -raw assembly. Additionally, if you're in the world of reverse engineering, programming in assembly keeps your -languages consistent. +notable projects in MASM in the last decade. + +Small, fast code just isn't as important as it used to be. Still, it is a very interesting exercise to learn MASM and use it. It's difficult to get binary sizes smaller than you can with raw assembly. Additionally, if you're in the world of reverse engineering, programming in assembly keeps your languages consistent. ## Table of Contents 1. [Getting Started](#getting-started) - 1. [The Assembler](#the-assembler) - 2. [IDEs](#ides) - 3. [VIM Plugins](#vim-plugins) - 4. [Visual Studio Code Extensions](#visual-studio-code-extensions) + 1. [The Assembler](#the-assembler) + 2. [IDEs](#ides) + 3. [VIM Plugins](#vim-plugins) + 4. [Visual Studio Code Extensions](#visual-studio-code-extensions) 2. [Tutorials](#tutorials) 3. [Styleguide](#styleguide) - 1. [Tabs vs. Spaces](#tabs-vs-spaces) - 2. [Line Length](#line-length) - 3. [Commenting](#commenting) - 4. [Include Ordering](#include-ordering) - 5. [Case Sensitivity](#case-sensitivity) - 6. [Section Names](#section-names) - 7. [Variable Names](#variable-names) - 8. [Functions](#functions) - 9. [Function Prototypes](#function-prototypes) - 10. [Section](#section) - 11. [Type Declarations](#type-declarations) - 12. [Alignment](#alignment) - 13. [Project Organization](#project-organization) + 1. [Tabs vs. Spaces](#tabs-vs-spaces) + 2. [Line Length](#line-length) + 3. [Commenting](#commenting) + 4. [Include Ordering](#include-ordering) + 5. [Case Sensitivity](#case-sensitivity) + 6. [Section Names](#section-names) + 7. [Variable Names](#variable-names) + 8. [Functions](#functions) + 9. [Function Prototypes](#function-prototypes) + 10. [Section](#section) + 11. [Type Declarations](#type-declarations) + 12. [Alignment](#alignment) + 13. [Project Organization](#project-organization) + ## Getting Started -You're going to want to get some development tools. Of course, it goes without saying you're going to need some flavor -of Windows to run this stuff. Once you've acquired Windows, you will need the assembler and an IDE (optionally). +You'll want to get some development tools. Of course, it goes without saying: you're going to need some flavor +of Windows to run this stuff. Once you've configured Windows, you will need the assembler and optionally an IDE. ### The Assembler -The most popular variant of MASM is [MASM32](http://www.masm32.com). It's more or less an all in one package for +The most popular variant of MASM is [MASM32 SDK](http://www.masm32.com). It's more or less an all in one package for coding assembly programs on Windows. One caveat - you'll need Windows 2000 or greater. This guide will focus on MASM32 primarily. Suggestions here should be easily ported to other variants. ### IDEs -Thanks to the popularity of MASM, there are a few IDE choices if you choose to go that route. They are helpful, in that +Thanks to the popularity of MASM, there are a couple IDE choices if you choose to go the route of using one. They are helpful, in that they handle assembling and linking for you. However, it's honestly something you can handle with a script. #### WinAsm Studio [WinAsm Studio](http://www.winasm.net) is arguably the most popular IDE for writing assembly code on Windows -(as far as I've known). As it stands, I've had difficulty creating a new account on their forum to download the -IDE. Unfortunately, they "account wall" the download so if you can't make an account you won't get the download. It's -quite silly. +(as far as I'm aware). As it stands, I've had difficulty creating a new account on their forum to download the +IDE. Unfortunately, they "account wall" the download so if you can't make a forum account, you won't get the download. (It's +quite silly.) #### VisualMASM [VisualMASM](http://www.visualmasm.com/) is another popular IDE. It's tailored to MASM and has the look and feel of a modern IDE. The most frustrating aspect is that there's no option to create a blank project. So if you're using -a template, you're going to need to delete the base code that comes with the project to get anywhere. I have -[an issue](https://github.com/ThomasJaeger/VisualMASM/issues/5) on the VisualMASM github to address this. +a template, you're going to need to delete the base code that comes with the project to start. I have +[an issue](https://github.com/ThomasJaeger/VisualMASM/issues/5) on the VisualMASM repo in GitHub to address this. ### VIM Plugins -VIM has pretty good support for assembly programming out of the box. I couldn't find any plugins that made programming -any easier. +[VIM](http://www.vim.org/scripts/script.php?script_id=966) has pretty good support for assembly programming out of the box. I couldn't find any plugins that made programming any easier. ### Visual Studio Code Extensions @@ -79,7 +78,7 @@ There is a `.CHM` version of these tutorials available on the [WinAsm website](h ## Styleguide The styleguide is a work in progress. As I find more pretty ways to write assembly code I will put them here. I've -gathered over my time writing MASM code that every developer does things differently. This makes it incredibly +realized over my time writing MASM code that every developer does things differently. This makes it incredibly frustrating to try and read another developer's code. _PS: It would be really cool if someone wrote a linter that checked for these things. Maybe I'll get around to it @@ -163,7 +162,7 @@ includelib \masm32\lib\kernel32.lib ### Variable Names -TODO - Once this is clarified be sure to update any variable names in every section to reflect this change. +TODO - Once this is clarified, be sure to update any variable names in every section to reflect this change. ### Functions @@ -180,12 +179,12 @@ Example: WinMain EndP ``` -Additionally, place your functions towards the bottom of your code section. This keeps your actual code uncluttered, -and all of your functions in one easy to find place. +Additionally, place your functions toward the bottom of your code section. This keeps your actual code uncluttered, +and all of your functions in one easy-to-find place. ### Function Prototypes -In order to allow the use of functions at the bottom of your code you need to declare function prototypes above +In order to allow the use of functions at the bottom of your code, you need to declare function prototypes above the invoking code. Place prototypes after all includes, and leave two empty lines between the includes and prototypes. @@ -218,7 +217,7 @@ Example: ### Sections In order to improve readability, indent the code in each section one level to differentiate it from the section name. -This makes it so, when combined with all uppercase section names, It is easier to distinguish where you are in the code. +This makes it so, when combined with all uppercase section names, it is easier to distinguish where you are in the code. Example: