Update README.md and CONTRIBUTING.md (#880)

* Update README.md and CONTRIBUTING.md

* typo

* style

* comma

CONTRIBUTING.md

@@ -15,6 +15,8 @@ To access the Ghidra repository, use the following details:
 - Address: `server.mattkc.com`
 - Port: `13100`
 
+**Please note that at the time of writing, much of the information found on the Ghidra server is severely outdated**. Generally, the source code found in this repository represents the latest "source of truth" and should be referenced whenever possible.
+
 ## General Guidelines
 
 If you feel fit to contribute, feel free to create a pull request! Someone will review and merge it (or provide feedback) as soon as possible.
@@ -26,6 +28,7 @@ This repository currently has only one goal: accuracy to the original executable
 ## Overview
 
 * [`3rdparty`](/3rdparty): Contains code obtained from third parties, not including Mindscape. Generally, these are libraries that have been placed in the public domain or are freely available on the web. As these are unaltered files, our style guide (see below) does not apply.
+* [`CONFIG`](/CONFIG): Decompilation of `CONFIG.EXE`. It depends on some code in `LEGO1`.
 * [`ISLE`](/ISLE): Decompilation of `ISLE.EXE`. It depends on some code in `LEGO1`.
 * [`LEGO1`](/LEGO1): Decompilation of `LEGO1.DLL`. This folder contains code from Mindscape's custom in-house engine called **Omni** (file pattern: `mx*`), the LEGO Island-specific extensions for Omni and the game's code (file pattern: `lego*`) as well as several utility libraries developed by Mindscape.
 * [`tools`](/tools): A set of tools aiding in the decompilation effort.
@@ -33,7 +36,15 @@ This repository currently has only one goal: accuracy to the original executable
 
 ## Tooling
 
-Please make yourself familiar with the [available tooling and annotations](/tools/README.md).
+Please make yourself familiar with the [available tooling and annotations](/tools/README.md). These are generally required to contribute to the project.
+
+## Notes on MSVC 4.20
+
+As outlined in the [`README`](/README.md), Microsoft Visual C++ 4.20 is the compiler we use to build the game. 
+
+One important aspect to know about this compiler in the context of the decompilation project is that the assembly code generation is somewhat erratic. We call this peculiarity "compiler randomness" or entropy. In essence, what it comes down to is that changes to the code base, for instance in a header, can pseudo-randomly affect the code generation of functions in compilation units that include this header, even if the changes are completely unrelated to those functions. For example, by adding an extra (unused) inline function or an enum declaration in a header, the code in some functions may unexpectedly wind up looking different and our main tool, [`reccmp`](/tools/README.md), will report either a (significantly) reduced or increased accuracy for those functions. This issue roughly affects around ~5% of all decompiled functions.
+
+We are currently unaware of the exact nature of this phenomenon. Unfortunately it represents a significant obstacle in our effort to achieve 100% matching binaries. If you or anyone you know has knowledge about the compiler internals that lead to the described observations, please contact us.
 
 ## Code Style
 
@@ -41,7 +52,7 @@ In general, we're not exhaustively strict about coding style, but there are some
 
 ### Formatting
 
-We are currently using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) with a configuration file that aims to replicate the code formatting employed by the original developers. There are [integrations](https://clang.llvm.org/docs/ClangFormat.html#vim-integration) available for most editors and IDEs. The required `clang-format` version is `17.x`.
+We are currently using [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) with configuration files that aim to replicate the code formatting employed by the original developers. There are [integrations](https://clang.llvm.org/docs/ClangFormat.html#vim-integration) available for most editors and IDEs. The required `clang-format` version is `17.x`.
 
 ### Naming conventions
 

tools/README.md

@@ -162,16 +162,19 @@ Use `pip` to install the required packages to be able to use the Python tools fo
 pip install -r tools/requirements.txt
 ```
 
-* [`patch_c2.py`](/tools/patch_c2.py): Patches `C2.EXE` (part of MSVC 4.20), to get rid of a bugged warning
-* [`reccmp`](/tools/reccmp): Compares the original EXE or DLL with a recompiled EXE or DLL, provided a PDB file
-* [`verexp`](/tools/verexp): Verifies exports by comparing the exports of the original DLL and the recompiled DLL
 * [`decomplint`](/tools/decomplint): Checks the decompilation annotations (see above)
+* [`isledecomp`](/tools/isledecomp): A library that implements a parser to identify the decompilation annotations (see above)
 * [`ncc`](/tools/ncc): Checks naming conventions based on a set of rules
-* [`isledecomp`](/tools/isledecomp): A library that implements a parser to identify the "decompilation" annotations (see above)
+* [`reccmp`](/tools/reccmp): Compares an original binary with a recompiled binary, provided a PDB file
+* [`roadmap`](/tools/roadmap): Compares symbol locations in an original binary with the same symbol locations of a recompiled binary
+* [`verexp`](/tools/verexp): Verifies exports by comparing the exports of the original DLL and the recompiled DLL
+* [`vtable`](/tools/vtable): Asserts virtual table correctness by comparing a recompiled binary with the original
+* [`datacmp.py`](/tools/datacmp.py): Compares global data found in the original with the recompiled version 
+* [`patch_c2.py`](/tools/patch_c2.py): Patches `C2.EXE` (part of MSVC 4.20) to get rid of a bugged warning
 
 ## Testing
 
-`isledecomp` has a small suite of tests. Install `pylint` and run it, passing in the directory:
+`isledecomp` comes with a suite of tests. Install `pylint` and run it, passing in the directory:
 
 ```
 pip install pytest